ugcinc 4.0.2 → 4.1.1

package/dist/comments.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CommentsClient = void 0;
 const base_1 = require("./base");
+// =============================================================================
+// Comments Client
+// =============================================================================
 /**
  * Client for managing comments
  */

package/dist/graph-controller.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Graph Controller
+ *
+ * Centralized logic for automation graph management including:
+ * - Port computation
+ * - Connection management
+ * - Type compatibility checking
+ * - Workflow validation
+ * - For-each context validation
+ *
+ * All functions work with WorkflowNodeDefinition[] (embedded connection format).
+ */
+import type { WorkflowNodeDefinition, ComputedNode, NodePort, BasePortType, ValidationError, UserCreatableNodeType } from './automations/types';
+import type { ObjectSchemaField, ResolvedPreview } from './automations/nodes/types';
+import type { AutomationsClient } from './automations';
+/**
+ * Connection extracted from embedded inputs format for internal processing
+ */
+interface Connection {
+    id: string;
+    sourceNodeId: string;
+    sourceOutputId: string;
+    targetNodeId: string;
+    targetInputId: string;
+}
+/**
+ * Check if two port types are compatible for connection
+ * A connection is valid if:
+ * 1. The types match exactly (same base type and same isArray), OR
+ * 2. The source is an array type and target is 'object' (non-array), OR
+ * 3. The source is a union and includes a compatible type, OR
+ * 4. The target is a union and includes a compatible type, OR
+ * 5. Both are unions and have at least one common compatible type
+ *
+ * Note: Array inputs are strict - they only accept exact matches
+ */
+export declare function areTypesCompatible({ sourceType, sourceIsArray, targetType, targetIsArray, }: {
+    sourceType: BasePortType | BasePortType[];
+    sourceIsArray: boolean;
+    targetType: BasePortType | BasePortType[];
+    targetIsArray: boolean;
+}): boolean;
+/**
+ * Compute ports for a node based on its type and config.
+ * Uses the node definition's computePorts function.
+ *
+ * @param nodeType - The type of the node
+ * @param config - The node's configuration object
+ * @param client - Optional AutomationsClient for nodes that need to fetch data
+ * @param getConnectedOutput - Optional function to get connected output port info (for dynamic ports)
+ */
+export declare function computePortsForNode({ nodeType, config, client, getConnectedOutput, }: {
+    nodeType: UserCreatableNodeType;
+    config?: Record<string, unknown>;
+    client?: AutomationsClient;
+    getConnectedOutput?: (inputId: string) => {
+        type: BasePortType | BasePortType[];
+        isArray: boolean;
+        objectSchema?: ObjectSchemaField[];
+    } | null;
+}): Promise<{
+    inputs: NodePort[];
+    outputs: NodePort[];
+}>;
+/**
+ * Get all available automation nodes.
+ * Converts node definitions from the registry into ComputedNode format.
+ */
+export declare function getAllNodes(client?: AutomationsClient): Promise<ComputedNode[]>;
+/**
+ * Get a specific node by nodeId
+ */
+export declare function getNodeByType(nodeId: string, client?: AutomationsClient): Promise<ComputedNode | undefined>;
+/**
+ * Get the schema of array items for a node's output port.
+ * Returns null if schema is unknown or the output is not an array.
+ *
+ * @param nodeType - The type of the node (e.g., 'transcript', 'llm')
+ * @param nodeConfig - The node's configuration object
+ * @param outputPortId - The ID of the output port to get schema for
+ * @param client - Optional AutomationsClient for nodes that need to fetch data
+ * @returns The schema of array items, or null if unknown
+ */
+export declare function getOutputSchema({ nodeType, nodeConfig, outputPortId, client, }: {
+    nodeType: string;
+    nodeConfig: Record<string, unknown> | undefined;
+    outputPortId: string;
+    client?: AutomationsClient;
+}): Promise<ObjectSchemaField[] | null>;
+/**
+ * Derive Connection[] array from nodes for canvas rendering
+ *
+ * Connections are stored in the embedded inputs map format.
+ * This function extracts them into a flat array for canvas rendering.
+ */
+export declare function deriveConnections({ nodes }: {
+    nodes: WorkflowNodeDefinition[];
+}): Connection[];
+/**
+ * Add a connection to a node's inputs map
+ */
+export declare function addConnection({ nodes, sourceNodeId, sourceOutputId, targetNodeId, targetInputId, }: {
+    nodes: WorkflowNodeDefinition[];
+    sourceNodeId: string;
+    sourceOutputId: string;
+    targetNodeId: string;
+    targetInputId: string;
+}): WorkflowNodeDefinition[];
+/**
+ * Remove a connection from a node's inputs map
+ */
+export declare function removeConnection({ nodes, targetNodeId, targetInputId, }: {
+    nodes: WorkflowNodeDefinition[];
+    targetNodeId: string;
+    targetInputId: string;
+}): WorkflowNodeDefinition[];
+/**
+ * Remove all connections to/from a node
+ */
+export declare function removeNodeConnections({ nodes, nodeId, }: {
+    nodes: WorkflowNodeDefinition[];
+    nodeId: string;
+}): WorkflowNodeDefinition[];
+/**
+ * Clean up stale connections on load.
+ *
+ * Removes entries from node.inputs that reference ports that no longer exist
+ * in the node's resolvedPorts.inputs. This handles cases where ports were
+ * renamed or deleted but the old connection data persisted.
+ */
+export declare function cleanupStaleConnections({ nodes, }: {
+    nodes: WorkflowNodeDefinition[];
+}): WorkflowNodeDefinition[];
+/**
+ * Find the for-each context a node belongs to by tracing backwards.
+ *
+ * A node is "inside" a for-each context if, when tracing backwards through
+ * connections, we reach a for-each node via one of its OUTPUT ports.
+ *
+ * Returns the for-each node ID if inside a context, or null if outside all contexts.
+ */
+export declare function getForEachContext({ nodeId, nodes, }: {
+    nodeId: string;
+    nodes: WorkflowNodeDefinition[];
+}): string | null;
+/**
+ * Check if a connection would violate for-each context boundaries.
+ *
+ * A violation occurs when:
+ * 1. Source is OUTSIDE a for-each context and target is INSIDE,
+ *    AND the source would NOT become a "captured" node after this connection
+ * 2. Source and target are in DIFFERENT for-each contexts
+ *    (can't connect across different loops)
+ *
+ * "Captured" nodes are allowed - they will be expanded at runtime to execute
+ * once per for-each iteration (e.g., Account selector → Auto Post inside for-each).
+ *
+ * Returns true if the connection is INVALID (violation), false if allowed.
+ */
+export declare function checkCrossContextViolation({ sourceNodeId, targetNodeId, nodes, }: {
+    sourceNodeId: string;
+    targetNodeId: string;
+    nodes: WorkflowNodeDefinition[];
+}): boolean;
+/**
+ * Validate workflow and return structured errors for UI highlighting
+ */
+export declare function validateWorkflow({ nodes, }: {
+    nodes: WorkflowNodeDefinition[];
+}): Promise<ValidationError[]>;
+/**
+ * Get node IDs that have errors
+ */
+export declare function getErrorNodeIds({ errors }: {
+    errors: ValidationError[];
+}): string[];
+/**
+ * Get port errors for a specific node
+ */
+export declare function getPortErrorsForNode({ nodeId, errors, }: {
+    nodeId: string;
+    errors: ValidationError[];
+}): Array<{
+    portId: string;
+    message: string;
+}>;
+/**
+ * Check if there's a missing trigger error
+ */
+export declare function hasMissingTriggerError({ errors }: {
+    errors: ValidationError[];
+}): boolean;
+/**
+ * Check if there's a missing terminal error
+ */
+export declare function hasMissingTerminalError({ errors }: {
+    errors: ValidationError[];
+}): boolean;
+/**
+ * Resolve preview data for a node.
+ * Converts node config with refs (inputId/textInputId) to render-ready format.
+ * Delegates to the node definition's resolvePreview function if available.
+ *
+ * @returns ResolvedPreview with render-ready config, sources, and textContent,
+ *          or null if the node doesn't support preview or config is invalid.
+ */
+export declare function resolveNodePreview({ nodes, nodeId, }: {
+    nodes: WorkflowNodeDefinition[];
+    nodeId: string;
+}): ResolvedPreview | null;
+export {};