ugcinc 4.0.2 → 4.1.0

package/dist/automations/types.d.ts

@@ -0,0 +1,544 @@
+/**
+ * Automation Types
+ *
+ * Core types for the automation system including ports, selection, and output modes.
+ */
+import type { ObjectSchemaField } from './nodes/types';
+import type { VideoEditorNodeConfig, ImageEditorNodeConfig } from '../render/types';
+import type { ManualTriggerNodeConfig } from './nodes/manual-trigger';
+import type { RecurrenceNodeConfig } from './nodes/recurrence';
+import type { OutputNodeConfig } from './nodes/output';
+import type { AccountNodeConfig } from './nodes/account';
+import type { AutoPostNodeConfig } from './nodes/auto-post';
+import type { SaveToMediaNodeConfig } from './nodes/save-to-media';
+import type { VideoImportNodeConfig } from './nodes/video-import';
+import type { RandomRouteNodeConfig } from './nodes/random-route';
+import type { BranchNodeConfig } from './nodes/branch';
+import type { AutoCaptionNodeConfig } from './nodes/auto-caption';
+import type { ScreenshotAnimationConfig } from './nodes/screenshot-animation';
+import type { CreateDmNodeConfig } from './nodes/create-dm';
+import type { CollectNodeConfig } from './nodes/collect';
+/**
+ * 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;
+/**
+ * Selection order configuration for media nodes
+ */
+export type SelectionMode = 'random' | 'sequential';
+export type ExhaustionBehavior = 'restart' | 'error';
+export interface SelectionConfig {
+    mode?: SelectionMode;
+    enforceUniqueness?: boolean;
+    exhaustionBehavior?: ExhaustionBehavior;
+}
+export interface SelectionState {
+    usedIndices: number[];
+    currentIndex: number;
+}
+/**
+ * Output mode for source nodes (image, video, audio, text)
+ * - 'per-input': Generate a unique value for each consumer input (default)
+ * - 'single': Use the same value for all consumer inputs
+ */
+export type OutputMode = 'per-input' | 'single';
+/**
+ * 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[];
+}
+/**
+ * Node types array for runtime use
+ */
+export declare const NodeTypes: readonly ["social-audio", "text", "media", "video-import", "image-composer", "video-composer", "generate-image", "generate-video", "custom-model", "llm", "passthrough", "manual-trigger", "recurrence", "compose-workflow", "account", "auto-post", "save-to-media", "deduplicate", "for-each", "for-each-value", "transcript", "auto-caption", "screenshot-animation", "random", "random-route", "branch", "if", "not", "create-dm", "collect", "destructure"];
+/**
+ * Node type enum derived from NodeTypes const array
+ * This is the canonical type - use this instead of the string union NodeTypeEnum
+ */
+export type NodeType = typeof NodeTypes[number];
+/**
+ * User-creatable node types (excludes internal executor types like 'for-each-value')
+ * These are the nodes that appear in the node picker and have definitions.
+ */
+export declare const UserCreatableNodeTypes: readonly ["social-audio", "text", "media", "video-import", "image-composer", "video-composer", "generate-image", "generate-video", "custom-model", "llm", "passthrough", "manual-trigger", "recurrence", "compose-workflow", "account", "auto-post", "save-to-media", "deduplicate", "for-each", "transcript", "auto-caption", "screenshot-animation", "random", "random-route", "branch", "if", "not", "create-dm", "collect", "destructure"];
+/**
+ * Type for user-creatable nodes only
+ */
+export type UserCreatableNodeType = typeof UserCreatableNodeTypes[number];
+/**
+ * @deprecated Use NodeType instead - this is a duplicate string union
+ */
+export type NodeTypeEnum = 'social-audio' | 'text' | 'media' | 'video-import' | 'image-composer' | 'video-composer' | 'generate-image' | 'generate-video' | 'custom-model' | 'llm' | 'passthrough' | 'manual-trigger' | 'recurrence' | 'compose-workflow' | 'account' | 'auto-post' | 'save-to-media' | 'deduplicate' | 'for-each' | 'for-each-value' | 'random' | 'random-route' | 'branch' | 'if' | 'not' | 'transcript' | 'auto-caption' | 'screenshot-animation' | 'create-dm' | 'collect' | 'destructure';
+/**
+ * Functional category for automation nodes
+ * - trigger: Nodes that start an automation (manual-trigger, recurrence)
+ * - source: Nodes that provide input data (image, video, audio, social-audio, text, account)
+ * - generator: Nodes that transform or generate content (image-composer, video-composer, generate-image, llm, compose-workflow)
+ * - terminal: Nodes that end an automation (output, auto-post, save-to-media)
+ */
+export type NodeCategory = 'trigger' | 'source' | 'generator' | 'terminal';
+export interface NodeControlConfig {
+    /** 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;
+    inputs: NodePort[];
+    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>;
+}
+/**
+ * Node definition for the centralized graph controller.
+ * Each node type defines its default config and port computation logic.
+ */
+export interface NodeDefinition {
+    /** Node type identifier - must match UserCreatableNodeType (e.g., 'collect', 'for-each', 'llm') */
+    nodeId: UserCreatableNodeType;
+    /** Display label for the node */
+    label: string;
+    /** Description shown in add node modal */
+    description: string;
+    /** Functional type for node behavior classification */
+    type: NodeCategory;
+    /** UI display category for grouping in add node modal */
+    category: string;
+    /**
+     * If true, this node supports generating multiple unique outputs per run
+     * when outputMode is 'per-input'. Used for source nodes like media, text.
+     */
+    supportsPerInputMode?: boolean;
+    /**
+     * Returns the default configuration when a node of this type is created.
+     * Should return a valid config that produces valid ports.
+     */
+    getDefaultConfig: () => Record<string, unknown>;
+    /**
+     * Computes the input and output ports for this node based on its config.
+     *
+     * @param config - The node's current configuration
+     * @param getConnectedOutput - Optional callback to get the output port of a connected source node.
+     *                             Used for objectSchema propagation through passthrough nodes.
+     * @returns The computed input and output ports
+     */
+    computePorts: (params: {
+        config: Record<string, unknown>;
+        getConnectedOutput?: (inputId: string) => {
+            type: BasePortType | BasePortType[];
+            isArray: boolean;
+            objectSchema?: ObjectSchemaField[];
+        } | null;
+    }) => {
+        inputs: NodePort[];
+        outputs: NodePort[];
+    };
+}
+export interface OutputSchemaProperty {
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+    items?: 'string' | 'number' | 'boolean';
+    properties?: Record<string, OutputSchemaProperty>;
+}
+export interface WorkflowNodeDefinition {
+    id: string;
+    type: NodeTypeEnum;
+    name?: string;
+    x?: number;
+    y?: number;
+    inputs: Record<string, {
+        sourceNodeId: string;
+        sourceOutputId: string;
+    }>;
+    config?: {
+        urls?: string[];
+        selectionConfig?: SelectionConfig;
+        selectionState?: SelectionState;
+        outputMode?: OutputMode;
+        outputs?: Array<{
+            id: string;
+            type: string;
+            isArray: boolean;
+            selectedMediaIds: string[];
+        }>;
+        textOptions?: string[];
+        videoEditor?: VideoEditorNodeConfig;
+        imageEditor?: ImageEditorNodeConfig;
+        outputSchema?: Record<string, OutputSchemaProperty>;
+        provider?: 'groq' | 'openai' | 'claude' | 'gemini';
+        model?: string;
+        temperature?: number;
+        maxTokens?: number;
+        useWebSearch?: boolean;
+        useStructuredOutput?: boolean;
+        manualTriggerConfig?: ManualTriggerNodeConfig;
+        recurrenceConfig?: RecurrenceNodeConfig;
+        workflowTemplateId?: string;
+        workflowVariableNameToIdMap?: Record<string, string>;
+        /** Resolved ports from the sub-workflow template (for validation) */
+        resolvedPorts?: ResolvedPorts;
+        outputConfig?: OutputNodeConfig;
+        accountConfig?: AccountNodeConfig;
+        autoPostConfig?: AutoPostNodeConfig;
+        saveToMediaConfig?: SaveToMediaNodeConfig;
+        videoImportConfig?: VideoImportNodeConfig;
+        randomRouteConfig?: RandomRouteNodeConfig;
+        branchConfig?: BranchNodeConfig;
+        autoCaptionConfig?: AutoCaptionNodeConfig;
+        screenshotAnimationConfig?: ScreenshotAnimationConfig;
+        createDmConfig?: CreateDmNodeConfig;
+        collectConfig?: CollectNodeConfig;
+    };
+}
+export interface CanvasState {
+    zoom: number;
+    panX: number;
+    panY: number;
+}
+export interface WorkflowDefinition {
+    nodes: WorkflowNodeDefinition[];
+    canvasState?: CanvasState;
+}
+/**
+ * Template node as stored in the database
+ */
+export interface TemplateNode {
+    id: string;
+    template_id: string;
+    node_id: string;
+    type: NodeTypeEnum;
+    name: string | null;
+    x: number;
+    y: number;
+    inputs: Record<string, {
+        sourceNodeId: string;
+        sourceOutputId: string;
+    }>;
+    config: WorkflowNodeDefinition['config'] | null;
+    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;
+}
+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: NodeTypeEnum;
+    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,101 @@
+"use strict";
+/**
+ * Automation Types
+ *
+ * Core types for the automation system including ports, selection, and output modes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserCreatableNodeTypes = exports.NodeTypes = 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;
+}
+// =============================================================================
+// Node Type Enums
+// =============================================================================
+/**
+ * Node types array for runtime use
+ */
+exports.NodeTypes = [
+    'social-audio',
+    'text',
+    'media',
+    'video-import',
+    'image-composer',
+    'video-composer',
+    'generate-image',
+    'generate-video',
+    'custom-model',
+    'llm',
+    'passthrough',
+    'manual-trigger',
+    'recurrence',
+    'compose-workflow',
+    'account',
+    'auto-post',
+    'save-to-media',
+    'deduplicate',
+    'for-each',
+    'for-each-value',
+    'transcript',
+    'auto-caption',
+    'screenshot-animation',
+    'random',
+    'random-route',
+    'branch',
+    'if',
+    'not',
+    'create-dm',
+    'collect',
+    'destructure',
+];
+/**
+ * User-creatable node types (excludes internal executor types like 'for-each-value')
+ * These are the nodes that appear in the node picker and have definitions.
+ */
+exports.UserCreatableNodeTypes = [
+    'social-audio',
+    'text',
+    'media',
+    'video-import',
+    'image-composer',
+    'video-composer',
+    'generate-image',
+    'generate-video',
+    'custom-model',
+    'llm',
+    'passthrough',
+    'manual-trigger',
+    'recurrence',
+    'compose-workflow',
+    'account',
+    'auto-post',
+    'save-to-media',
+    'deduplicate',
+    'for-each',
+    'transcript',
+    'auto-caption',
+    'screenshot-animation',
+    'random',
+    'random-route',
+    'branch',
+    'if',
+    'not',
+    'create-dm',
+    'collect',
+    'destructure',
+];
+/**
+ * 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 };