ugcinc 4.0.2 → 4.1.1

package/dist/automations/types.d.ts

@@ -0,0 +1,431 @@
+/**
+ * Automation Types
+ *
+ * Core types for the automation system including ports, selection, and output modes.
+ */
+import type { ObjectSchemaField, SelectionMode, OutputMode, NodeCategory } from './nodes/types';
+import type { NodeType, UserCreatableNodeType, WorkflowConfig, InternalNodeType } from './nodes';
+/**
+ * Media type for automation nodes
+ */
+export type MediaType = 'video' | 'image' | 'audio' | 'text';
+/**
+ * Base port type - all possible value types without array modifier
+ */
+export type BasePortType = 'image' | 'video' | 'audio' | 'text' | 'number' | 'boolean' | 'object' | 'account' | 'date' | 'social_audio' | 'enum';
+/**
+ * Option for enum port types
+ */
+export interface EnumOption {
+    label: string;
+    value: string;
+}
+/**
+ * Format a port type for display (e.g., 'image' with isArray=true -> 'image[]')
+ */
+export declare function formatPortType(type: BasePortType | BasePortType[], isArray: boolean): string;
+/**
+ * Standard node output format.
+ * All nodes output their values in the _values array.
+ * - For per-input mode: _values contains N values (one per consumer)
+ * - For single mode: _values contains 1 value
+ *
+ * Downstream nodes always read from _values using resolveValueAtIteration().
+ */
+export interface NodeOutputValues {
+    _values: unknown[];
+    _outputMode: OutputMode;
+}
+export interface NodePort {
+    id: string;
+    type: BasePortType | BasePortType[];
+    isArray: boolean;
+    required: boolean;
+    /** Schema of object properties (when this port outputs an object) */
+    objectSchema?: ObjectSchemaField[];
+    /** Options for enum port types */
+    enumOptions?: EnumOption[];
+}
+/**
+ * Port definition for resolved/dynamic ports.
+ * Stored in node config when the automation is saved.
+ */
+export interface ResolvedPort {
+    id: string;
+    type: BasePortType | BasePortType[];
+    isArray: boolean;
+    required: boolean;
+    /** Schema of object properties (when this port outputs an object) */
+    objectSchema?: ObjectSchemaField[];
+}
+/**
+ * Resolved ports for nodes with dynamic inputs/outputs.
+ * Stored in node config when the automation is saved, allowing validation
+ * without needing to resolve ports at validation time.
+ * Note: Uses simplified ResolvedPort type for database compatibility.
+ */
+export interface ResolvedPorts {
+    inputs: ResolvedPort[];
+    outputs: ResolvedPort[];
+}
+export type { NodeType, UserCreatableNodeType, NodeConfig, WorkflowConfig, InternalNodeType, NodeDefinition } from './nodes';
+export { nodeDefinitions, internalNodeTypes } from './nodes';
+/**
+ * Pre-computed node definition with static ports.
+ * Returned by getAllNodes() and getNodeByType() for consumer convenience.
+ * Ports are pre-computed from the node's defaults - consumers don't need to call computePorts.
+ */
+export interface ComputedNode {
+    /** Node type identifier (e.g., 'collect', 'for-each', 'llm') */
+    nodeId: string;
+    /** Display label for the node */
+    label: string;
+    /** Description shown in add node modal */
+    description: string;
+    /** UI display category for grouping in add node modal */
+    category: string;
+    /** Functional type for node behavior classification */
+    type: NodeCategory;
+    /** Pre-computed input ports based on defaults */
+    inputs: NodePort[];
+    /** Pre-computed output ports based on defaults */
+    outputs: NodePort[];
+    /** Available output modes, or null if not applicable */
+    outputModes: OutputMode[] | null;
+    /** Available selection modes, or null if not applicable */
+    selectionModes: SelectionMode[] | null;
+    /** Default config values for this node */
+    defaults: Record<string, unknown>;
+}
+export interface OutputSchemaProperty {
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+    items?: 'string' | 'number' | 'boolean';
+    properties?: Record<string, OutputSchemaProperty>;
+}
+/** Base fields shared by all workflow nodes */
+type WorkflowNodeDefinitionBase = {
+    id: string;
+    name?: string;
+    x?: number;
+    y?: number;
+    inputs: Record<string, {
+        sourceNodeId: string;
+        sourceOutputId: string;
+    }>;
+};
+/**
+ * Discriminated union of workflow node definitions.
+ * Each node type has its specific config type, enabling automatic type narrowing.
+ */
+export type WorkflowNodeDefinition = {
+    [K in UserCreatableNodeType]: WorkflowNodeDefinitionBase & {
+        type: K;
+        config: WorkflowConfig[K];
+    };
+}[UserCreatableNodeType];
+export interface CanvasState {
+    zoom: number;
+    panX: number;
+    panY: number;
+}
+export interface WorkflowDefinition {
+    nodes: WorkflowNodeDefinition[];
+    canvasState?: CanvasState;
+}
+/** Base fields shared by all template nodes */
+type TemplateNodeBase = {
+    id: string;
+    template_id: string;
+    node_id: string;
+    name: string | null;
+    x: number;
+    y: number;
+    inputs: Record<string, {
+        sourceNodeId: string;
+        sourceOutputId: string;
+    }>;
+    cached_output: Record<string, unknown> | null;
+    cached_at: string | null;
+    cached_run_id: string | null;
+    cached_variable_inputs: Record<string, string> | null;
+    preview_outputs: Record<string, string> | null;
+    created_at: string;
+    updated_at: string;
+};
+/** User-creatable template nodes have typed config */
+type UserCreatableTemplateNode = {
+    [K in UserCreatableNodeType]: TemplateNodeBase & {
+        type: K;
+        config: WorkflowConfig[K] | null;
+    };
+}[UserCreatableNodeType];
+/** Internal template nodes (created during execution) have no config */
+type InternalTemplateNode = {
+    [K in InternalNodeType]: TemplateNodeBase & {
+        type: K;
+        config: null;
+    };
+}[InternalNodeType];
+/**
+ * Template node as stored in the database.
+ * Discriminated union enabling automatic type narrowing based on node type.
+ */
+export type TemplateNode = UserCreatableTemplateNode | InternalTemplateNode;
+export interface AutomationTemplate {
+    id: string;
+    org_id: string;
+    name: string;
+    description: string | null;
+    canvas_state: CanvasState | null;
+    nodes: TemplateNode[];
+    preview_output: string | null;
+    output_schema: Record<string, {
+        type: string;
+    }> | null;
+    recurrence_enabled: boolean;
+    next_run_at: string | null;
+    last_run_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface AutomationRun {
+    id: string;
+    template_id: string;
+    org_id: string;
+    tag: string | null;
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    variable_inputs: Record<string, string> | null;
+    save_as_preview: boolean | null;
+    create_post: boolean | null;
+    require_review: boolean | null;
+    review_status: 'pending_review' | 'approved' | 'rejected' | null;
+    created_at: string;
+    completed_at: string | null;
+}
+/**
+ * Executor node from the edge-based execution model.
+ * Each executor represents one instance of a template node during execution.
+ */
+export interface ExecutorNode {
+    id: string;
+    template_node_id: string;
+    executor_index: number;
+    type: NodeType;
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    output_value: unknown | null;
+    error_message: string | null;
+    created_at: string;
+    completed_at: string | null;
+}
+/**
+ * Execution edge from the edge-based execution model.
+ * Represents a data flow connection between two executors.
+ */
+export interface ExecutionEdge {
+    id: string;
+    source_executor_id: string;
+    source_port: string;
+    target_executor_id: string;
+    target_port: string;
+    value: unknown | null;
+}
+/**
+ * Account object that flows through edges for posting
+ */
+export interface AccountData {
+    id: string;
+    username: string;
+    platform: 'tiktok';
+    displayName?: string;
+    profilePicUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Output structure for flow control nodes (if, random-route).
+ * Contains values for selected ports and list of skipped port IDs.
+ */
+export interface FlowControlOutput {
+    values: Record<string, unknown>;
+    skippedPorts: string[];
+}
+/**
+ * Context passed to executor-based node execution.
+ * Replaces the complex outputMap/iteration/portOffsets pattern with simple inputs.
+ */
+export interface ExecutorContext {
+    /** Database ID of this executor */
+    executorId: string;
+    /** Run ID this executor belongs to */
+    runId: string;
+    /** Template node ID this executor was created from */
+    templateNodeId: string;
+    /** Index of this executor (0, 1, 2...) for the same template node */
+    executorIndex: number;
+    /** Node type */
+    type: NodeType;
+    /** Node config (includes assignedValue for source nodes) */
+    config: Record<string, unknown>;
+    /** Input values read from incoming edges (portId -> value) */
+    inputs: Record<string, unknown>;
+}
+/**
+ * Executor for synchronous nodes.
+ * Much simpler than the old NodeControlConfig - just takes context and returns output.
+ */
+export interface NodeExecutor<TOutput = unknown> {
+    type: NodeType;
+    /**
+     * Execute the node and return a single output value.
+     * For multi-output nodes (like LLM), return an object with output fields.
+     */
+    execute: (ctx: ExecutorContext) => Promise<TOutput>;
+}
+/**
+ * Async job status for executor-based async nodes
+ */
+export type ExecutorAsyncJobStatus<TOutput = unknown> = {
+    status: 'pending';
+} | {
+    status: 'completed';
+    output: TOutput;
+} | {
+    status: 'failed';
+    error: string;
+};
+/**
+ * Executor for asynchronous nodes (video-editor, generate-image, workflow).
+ * Uses submit/poll pattern for durable workflows.
+ */
+export interface AsyncNodeExecutor<TOutput = unknown> extends Omit<NodeExecutor<TOutput>, 'execute'> {
+    isAsync: true;
+    /** Submit job - returns job ID for polling */
+    submitJob: (ctx: ExecutorContext) => Promise<{
+        jobId: string;
+    }>;
+    /** Check job status - called by orchestrator with workflow sleep between calls */
+    checkStatus: (jobId: string, ctx: ExecutorContext) => Promise<ExecutorAsyncJobStatus<TOutput>>;
+}
+/**
+ * Type guard to check if an executor is async
+ */
+export declare function isAsyncExecutor<T>(executor: NodeExecutor<T> | AsyncNodeExecutor<T>): executor is AsyncNodeExecutor<T>;
+/**
+ * Validation error types for automation workflows
+ */
+export type ValidationErrorType = 'missing_trigger' | 'missing_terminal' | 'missing_required_input' | 'type_mismatch' | 'empty_media_pool' | 'empty_account_pool';
+/**
+ * Structured validation error with location info for UI highlighting
+ */
+export interface ValidationError {
+    type: ValidationErrorType;
+    nodeId?: string;
+    portId?: string;
+    message: string;
+}
+/**
+ * Exported node representation for debugging
+ */
+export interface ExportedNode {
+    nodeId: string;
+    type: string;
+    name: string | null;
+    position: {
+        x: number;
+        y: number;
+    };
+    inputs: Record<string, {
+        sourceNodeId: string;
+        sourceOutputId: string;
+    }>;
+    config: Record<string, unknown>;
+}
+/**
+ * Exported connection representation
+ */
+export interface ExportedConnection {
+    from: {
+        nodeId: string;
+        port: string;
+    };
+    to: {
+        nodeId: string;
+        port: string;
+    };
+}
+/**
+ * Exported template data
+ */
+export interface ExportedTemplate {
+    id: string;
+    name: string;
+    description: string | null;
+    canvasState: {
+        zoom: number;
+        panX: number;
+        panY: number;
+    } | null;
+    outputSchema: Record<string, {
+        type: string;
+    }> | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Full automation export (template + nodes + connections)
+ */
+export interface AutomationExport {
+    template: ExportedTemplate;
+    nodes: ExportedNode[];
+    connections: ExportedConnection[];
+}
+/**
+ * Exported executor data
+ */
+export interface ExportedExecutor {
+    id: string;
+    nodeTemplateId: string;
+    executorIndex: number;
+    type: string;
+    status: string;
+    outputValue: unknown;
+    errorMessage: string | null;
+    createdAt: string;
+    completedAt: string | null;
+}
+/**
+ * Exported edge data
+ */
+export interface ExportedEdge {
+    sourceExecutorId: string;
+    sourceNodeId: string;
+    sourcePort: string;
+    targetExecutorId: string;
+    targetNodeId: string;
+    targetPort: string;
+    value: unknown;
+}
+/**
+ * Exported run data
+ */
+export interface ExportedRun {
+    id: string;
+    templateId: string;
+    templateName: string;
+    status: string;
+    variableInputs: Record<string, string> | null;
+    createdAt: string;
+    completedAt: string | null;
+}
+/**
+ * Full automation run export
+ */
+export interface AutomationRunExport {
+    run: ExportedRun;
+    template: ExportedTemplate;
+    nodes: ExportedNode[];
+    connections: ExportedConnection[];
+    execution: {
+        executors: ExportedExecutor[];
+        edges: ExportedEdge[];
+    };
+}

package/dist/automations/types.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Automation Types
+ *
+ * Core types for the automation system including ports, selection, and output modes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.internalNodeTypes = exports.nodeDefinitions = void 0;
+exports.formatPortType = formatPortType;
+exports.isAsyncExecutor = isAsyncExecutor;
+/**
+ * Format a port type for display (e.g., 'image' with isArray=true -> 'image[]')
+ */
+function formatPortType(type, isArray) {
+    if (Array.isArray(type)) {
+        const types = type.map(t => isArray ? `${t}[]` : t);
+        return types.join(' | ');
+    }
+    return isArray ? `${type}[]` : type;
+}
+var nodes_1 = require("./nodes");
+Object.defineProperty(exports, "nodeDefinitions", { enumerable: true, get: function () { return nodes_1.nodeDefinitions; } });
+Object.defineProperty(exports, "internalNodeTypes", { enumerable: true, get: function () { return nodes_1.internalNodeTypes; } });
+/**
+ * Type guard to check if an executor is async
+ */
+function isAsyncExecutor(executor) {
+    return 'isAsync' in executor && executor.isAsync === true;
+}

package/dist/automations.d.ts

@@ -1,20 +1,11 @@
-import type { NodeControlConfig, NodeCategory, MediaType, NodePort, NodeTypeEnum, PortType, WorkflowDefinition, AutomationTemplate, AutomationRun, ExecutorNode, ExecutionEdge, ApiResponse, AutomationExport, AutomationRunExport, PropertySchema } from './types';
-import { BaseClient } from './base';
 /**
- * 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 PortType[] and includes a compatible type, OR
- * 4. The target is a PortType[] and includes a compatible type, OR
- * 5. Both are PortType[] and have at least one common compatible type
+ * Automations API Client
  *
- * Note: Array inputs are strict - they only accept exact matches
+ * Provides methods to interact with the UGC Inc Automations API.
+ * For graph logic (validation, port computation, connections), use graph-controller.ts
  */
-export declare function areTypesCompatible({ sourceType, targetType, }: {
-    sourceType: PortType | PortType[];
-    targetType: PortType | PortType[];
-}): boolean;
+import type { WorkflowDefinition, AutomationTemplate, AutomationRun, ExecutorNode, ExecutionEdge, ApiResponse, AutomationExport, AutomationRunExport } from './types';
+import { BaseClient } from './base';
 export declare class AutomationsClient extends BaseClient {
     /**
      * List all automation templates for an organization
@@ -180,22 +171,3 @@ export declare class AutomationsClient extends BaseClient {
         runIds: string[];
     }>>;
 }
-/**
- * Get all available automation nodes
- */
-export declare function getAllNodes(): NodeControlConfig[];
-/**
- * Get a specific node by type
- */
-export declare function getNodeByType(type: string): NodeControlConfig | 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
- * @returns The schema of array items, or null if unknown
- */
-export declare function getOutputSchema(nodeType: string, nodeConfig: Record<string, unknown> | undefined, outputPortId: string): Record<string, PropertySchema> | null;
-export type { NodeControlConfig, NodeCategory, MediaType, NodePort, NodeTypeEnum, PropertySchema };