@octaviaflow/flow-rules 0.9.0 → 0.11.0

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

@@ -0,0 +1,78 @@
+/**
+ * Cloud Storage Action Configuration (the unified action users add)
+ *
+ * This contract is DERIVED from `storageCapabilities.ts` — the same table
+ * StorageConfigPanel renders from — so the panel and the contract cannot
+ * disagree about which keys exist. Three groups:
+ *
+ * 1. Fixed keys every operation shares (`connector`, `operation`, …) and the
+ *    Transfer / Sync keys (`destConnector`, `destPath`, `cursor`, …).
+ * 2. One `string` per path / destination key any provider uses (`key`, `blob`,
+ *    `remotePath`, `path`, `prefix`, `fileId`, `folderId`, `destKey`, …) and
+ *    its `<key>Name` companion — the picked item's display name, written by
+ *    the FilePicker and never read by the Engine.
+ * 3. Every extra field any operation declares (`maxKeys`, `expiresIn`,
+ *    `contentType`, `mode`, `query`, `pageSize`, `fileName`, `mimeType`,
+ *    `shareEmail`, `shareRole`, `ifExists`, `onError`), typed from its spec.
+ *
+ * Plus the three keys the Engine reads from config ahead of the connector's
+ * credentials: `bucket`, `container`, `region`.
+ *
+ * Which keys an OPERATION needs is per provider × operation and lives in the
+ * capability table; `validate()` checks only what blocks execution for
+ * every provider.
+ */
+import { type StorageOperation } from '../storageCapabilities';
+type StorageSchemaField = {
+    type: string;
+    required?: boolean;
+    options?: ReadonlyArray<string | number>;
+    description?: string;
+    min?: number;
+};
+export interface StorageActionConfigType {
+    /** The storage connector instance (a connection id); its provider decides the operations. */
+    connector: string;
+    operation: StorageOperation;
+    /** Name of this step's output in the run's data bag. */
+    outputAs?: string;
+    /** upload: the body. */
+    content?: string;
+    /** transfer / sync: the destination connector instance. */
+    destConnector?: string;
+    /** transfer / sync: destination path (a folder when empty or ending in `/`). */
+    destPath?: string;
+    /** transfer: copy a folder recursively. */
+    sourceIsDirectory?: boolean;
+    /** sync: the walk cursor threaded by a cursor ForEach — `{{$item.cursor}}` in the editor. */
+    cursor?: unknown;
+    /** sync: files per pass (200 by default). */
+    fileBudget?: number;
+    /** sync: milliseconds per pass (120000 by default). */
+    timeBudgetMs?: number;
+    /** list: keep only these extensions. */
+    fileTypes?: string[];
+    /** list: keep only names matching this glob. */
+    filePattern?: string;
+    /** S3 / GCS: overrides the connector's bucket. */
+    bucket?: string;
+    /** Azure: overrides the connector's container. */
+    container?: string;
+    /** S3: overrides the connector's region. */
+    region?: string;
+    /** Path, destination, companion-name and extra keys — see the capability table. */
+    [key: string]: unknown;
+}
+/** Every operation value any provider offers, in first-seen order. */
+export declare function storageOperations(): StorageOperation[];
+export declare const StorageActionConfig: {
+    defaults: StorageActionConfigType;
+    schema: Record<string, StorageSchemaField>;
+    validate: (config: Partial<StorageActionConfigType>) => {
+        valid: boolean;
+        errors: string[];
+    };
+    merge: (userConfig: Partial<StorageActionConfigType>) => StorageActionConfigType;
+    getLabel: (config: StorageActionConfigType) => string;
+};
+export {};

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

@@ -0,0 +1,123 @@
+/**
+ * XML Action Configuration
+ *
+ * What XmlConfigPanel writes and the Engine's xml_action case reads.
+ */
+import { type FileEditConfigType, type FileFormatOperation } from '../fileEditContract';
+export interface XmlActionConfigType extends FileEditConfigType {
+    /** `parse` (default when absent) | `generate` | `edit`. */
+    operation: FileFormatOperation;
+    /** Legacy alias for `operation`. */
+    mode?: string;
+    /** XML text, or an FX token from an upstream step. */
+    content?: string;
+    /** Legacy alias for `content`. */
+    inlineContent?: string;
+    /** `generate`: the document's root element (`data` by default). */
+    rootElement?: string;
+    /** The element that holds one record (`row` by default on generate; detected on parse). */
+    rowElement?: string;
+    /** `generate`: name of the produced file. */
+    fileName?: string;
+}
+export declare const XmlActionConfig: {
+    defaults: XmlActionConfigType;
+    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;
+        };
+        rootElement: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        rowElement: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        fileName: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+    };
+    validate: (config: Partial<XmlActionConfigType>) => {
+        valid: boolean;
+        errors: string[];
+    };
+    merge: (userConfig: Partial<XmlActionConfigType>) => XmlActionConfigType;
+    getLabel: (config: XmlActionConfigType) => string;
+};

package/dist/catalog/triggers/connector-trigger/config.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Connector Trigger Configuration
+ *
+ * What ConnectorTriggerPanel writes, what the Backend derives the
+ * registration from (`connectorInstanceId` + `events`, see
+ * connectorTriggerSync), and the one key the Engine reads (`description`).
+ *
+ * `connectorId`, `connectorName`, `subscribed`, `eventCount` and `summary` are
+ * written by the panel (and by the Backend on an agent's behalf) so the canvas
+ * and `check_flow` can read the registration without a second lookup. The
+ * Google Sheets keys apply only when `connectorId` is `google_sheets`.
+ */
+import { type ConnectorTriggerEvent } from './events';
+export interface ConnectorTriggerConfigType {
+    /** The connected app instance (a connection id). */
+    connectorInstanceId: string;
+    /** `[{ entity, operations: [...] }]` — exact names from the connector's vocabulary. Registers the trigger. */
+    events?: ConnectorTriggerEvent[];
+    /** Connector TYPE of the instance (`hubspot`, `google_sheets`, …), not an id. */
+    connectorId?: string;
+    /** Display name of the instance. */
+    connectorName?: string;
+    /** Registration snapshot: a subscription exists. */
+    subscribed?: boolean;
+    /** Registration snapshot: entity × operation pairs subscribed. */
+    eventCount?: number;
+    /** Registration snapshot: `Hubspot · 2 events`. */
+    summary?: string;
+    /** Google Sheets: the spreadsheet watched. */
+    sheetFileId?: string;
+    /** Google Sheets: the spreadsheet's name, for display. */
+    sheetFileLabel?: string;
+    /** Google Sheets: the tab watched. */
+    sheetName?: string;
+    /** Google Sheets: the column that identifies a row, for change detection. */
+    sheetKeyColumn?: string;
+    /** Free text the Engine adds to the trigger's output when set. */
+    description?: string;
+}
+export declare const ConnectorTriggerConfig: {
+    defaults: ConnectorTriggerConfigType;
+    schema: {
+        connectorInstanceId: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        events: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        connectorId: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        connectorName: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        subscribed: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        eventCount: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        summary: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        sheetFileId: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        sheetFileLabel: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        sheetName: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        sheetKeyColumn: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        description: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+    };
+    validate: (config: Partial<ConnectorTriggerConfigType>) => {
+        valid: boolean;
+        errors: string[];
+    };
+    merge: (userConfig: Partial<ConnectorTriggerConfigType>) => ConnectorTriggerConfigType;
+    getLabel: (config: ConnectorTriggerConfigType) => string;
+};

package/dist/catalog/triggers/connector-trigger/events.d.ts

@@ -0,0 +1,46 @@
+/**
+ * What a Connector Trigger can subscribe to, per connector.
+ *
+ * ONE vocabulary for the editor's panel and for an agent authoring over MCP.
+ * The trigger's `events` — `[{ entity, operations }]` — is what registers the
+ * flow's connector subscription, the record every inbound provider event is
+ * matched against: an entity name outside this list (or in the wrong case —
+ * HubSpot is lowercase, Salesforce is capitalised) registers a subscription
+ * that never fires, with no error anywhere. An agent wrote `lead` for a
+ * HubSpot contact trigger on 2026-09-26 and spent an hour on it.
+ *
+ * Copied as-is from octaviaflow-ui's ConnectorTriggerPanel (the panel's tables
+ * were the only copy); the panel is to import from here in its next flow-rules
+ * upgrade.
+ */
+export interface ConnectorEventEntity {
+    entity: string;
+    supportedOperations: string[];
+}
+/** One subscribed pair, as stored in a trigger step's `events`. */
+export interface ConnectorTriggerEvent {
+    entity: string;
+    operations: string[];
+}
+/**
+ * Connector ids that emit events a flow trigger can subscribe to. Database /
+ * http / openapi / ftp / etc. connectors are intentionally excluded: they
+ * cannot push events.
+ */
+export declare const EVENT_CAPABLE_CONNECTOR_IDS: ReadonlySet<string>;
+/** Every subscribable entity, by connector id. */
+export declare const CONNECTOR_EVENT_ENTITIES: Readonly<Record<string, ConnectorEventEntity[]>>;
+export declare function getEntitiesForConnector(connectorId: string): ConnectorEventEntity[];
+/** True when this connector type can drive an event trigger. */
+export declare function isEventCapableConnector(connectorId: string): boolean;
+/**
+ * The one-line summary the canvas shows under a Connector Trigger
+ * (`Hubspot · 4 events`) — the same string the panel writes.
+ */
+export declare function summarizeConnectorTriggerEvents(connectorName: string, events: ConnectorTriggerEvent[]): string;
+/**
+ * Why `events` cannot register a trigger on this connector — or `null` when
+ * it can. Names are matched EXACTLY, because the inbound matcher matches them
+ * exactly; a case-only miss says what was meant.
+ */
+export declare function validateConnectorTriggerEvents(connectorId: string, events: unknown): string | null;