ugcinc 4.1.55 → 4.1.57

package/dist/automations/nodes/branch.d.ts

@@ -1,4 +1,4 @@
-import type { NodePort, PortValue } from '../types';
+import type { NodePort, PortValue, FlowControlOutput } from '../types';
 import { type InputType, type OutputMode } from './types';
 /**
  * Branch node inputs: required key input + dynamic branch-specific inputs.
@@ -30,6 +30,7 @@ declare const definition: import("./types").NodeDefinition<"generator", {
 declare const _default: typeof definition & {
     __TInputs: BranchNodeInputs;
     __TOutputs: BranchNodeOutputs;
+    __TExecutorOutput: FlowControlOutput;
 };
 export default _default;
 export type BranchNodeConfig = typeof definition.defaults;

package/dist/automations/nodes/custom-model.d.ts

@@ -7,17 +7,58 @@ export interface CustomModelNodeOutputs {
     output: ImageValue | VideoValue | AudioValue;
 }
 export type CustomModelOutputType = 'image' | 'video' | 'audio';
+export type CustomModelParamType = 'string' | 'number' | 'boolean' | 'image' | 'video' | 'audio';
 export interface CustomModelInputParam {
     name: string;
-    type: string;
+    type: CustomModelParamType;
     required: boolean;
     description?: string;
     default?: unknown;
 }
+export interface OpenAPIProperty {
+    type?: string;
+    format?: string;
+    description?: string;
+    default?: unknown;
+    enum?: string[];
+    items?: {
+        type?: string;
+        $ref?: string;
+    };
+    $ref?: string;
+}
+interface OpenAPISchemaDefinition {
+    properties?: Record<string, OpenAPIProperty>;
+    required?: string[];
+    'x-fal-order-properties'?: string[];
+}
+export interface OpenAPISchema {
+    components?: {
+        schemas?: Record<string, OpenAPISchemaDefinition>;
+    };
+}
+/**
+ * Map OpenAPI type to our param type
+ */
+export declare function mapOpenAPIType(prop: OpenAPIProperty, name: string): CustomModelParamType;
+/**
+ * Parse OpenAPI schema to get input parameters
+ */
+export declare function parseOpenAPIInputs(schema: OpenAPISchema): CustomModelInputParam[];
+/**
+ * Parse OpenAPI schema to determine the output URL path.
+ * Returns a path like "images[0].url", "video.url", "audio.url", etc.
+ */
+export declare function parseOpenAPIOutputPath(schema: OpenAPISchema, outputType: CustomModelOutputType): string | null;
+/**
+ * Determine output type from fal.ai category string
+ */
+export declare function getOutputTypeFromCategory(category?: string): CustomModelOutputType;
 declare const definition: import("./types").NodeDefinition<"generator", {
     modelId: string;
     modelName: string;
     outputType: CustomModelOutputType;
+    outputUrlPath: string | null;
     inputParams: CustomModelInputParam[];
     apiKey: string | undefined;
     outputMode: OutputMode;

package/dist/automations/nodes/custom-model.js

@@ -1,7 +1,180 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapOpenAPIType = mapOpenAPIType;
+exports.parseOpenAPIInputs = parseOpenAPIInputs;
+exports.parseOpenAPIOutputPath = parseOpenAPIOutputPath;
+exports.getOutputTypeFromCategory = getOutputTypeFromCategory;
 const types_1 = require("./types");
 // =============================================================================
+// OpenAPI Parsing Functions
+// =============================================================================
+/** Helper types that should be excluded when searching for Input/Output schemas */
+const HELPER_TYPES = ['File', 'QueueStatus', 'HTTPValidationError', 'ValidationError', 'Image', 'Video', 'Audio'];
+/**
+ * Find the input schema from OpenAPI components.
+ * fal.ai names input schemas like "WanProImageToVideoInput" not just "Input"
+ */
+function findInputSchema(schemas) {
+    if (!schemas)
+        return null;
+    // First try exact "Input" name
+    if (schemas.Input)
+        return schemas.Input;
+    // Find schema that ends with "Input" (excluding helper types)
+    for (const [name, schema] of Object.entries(schemas)) {
+        if (name.endsWith('Input') && !HELPER_TYPES.includes(name)) {
+            return schema;
+        }
+    }
+    return null;
+}
+/**
+ * Find the output schema from OpenAPI components.
+ * fal.ai names output schemas like "WanProImageToVideoOutput" not just "Output"
+ */
+function findOutputSchema(schemas) {
+    if (!schemas)
+        return null;
+    // First try exact "Output" name
+    if (schemas.Output)
+        return schemas.Output;
+    // Find schema that ends with "Output" (excluding helper types)
+    for (const [name, schema] of Object.entries(schemas)) {
+        if (name.endsWith('Output') && !HELPER_TYPES.includes(name)) {
+            return schema;
+        }
+    }
+    return null;
+}
+/**
+ * Map OpenAPI type to our param type
+ */
+function mapOpenAPIType(prop, name) {
+    // Check for common image/video/audio input patterns
+    const nameLower = name.toLowerCase();
+    const descLower = (prop.description ?? '').toLowerCase();
+    if (nameLower.includes('image') || descLower.includes('image url')) {
+        return 'image';
+    }
+    if (nameLower.includes('video') || descLower.includes('video url')) {
+        return 'video';
+    }
+    if (nameLower.includes('audio') || descLower.includes('audio url')) {
+        return 'audio';
+    }
+    // Check format
+    if (prop.format === 'uri' || prop.format === 'binary') {
+        // Generic file input - assume image
+        return 'image';
+    }
+    // Map basic types
+    if (prop.type === 'integer' || prop.type === 'number') {
+        return 'number';
+    }
+    if (prop.type === 'boolean') {
+        return 'boolean';
+    }
+    return 'string';
+}
+/**
+ * Parse OpenAPI schema to get input parameters
+ */
+function parseOpenAPIInputs(schema) {
+    const schemas = schema.components?.schemas;
+    const inputSchema = findInputSchema(schemas);
+    if (!inputSchema?.properties) {
+        return [];
+    }
+    const params = [];
+    for (const [name, prop] of Object.entries(inputSchema.properties)) {
+        // Skip complex nested objects and arrays (for now)
+        if (prop.type === 'object' || (prop.type === 'array' && !prop.items)) {
+            continue;
+        }
+        params.push({
+            name,
+            type: mapOpenAPIType(prop, name),
+            required: inputSchema.required?.includes(name) ?? false,
+            description: prop.description,
+            default: prop.default,
+        });
+    }
+    // Sort: required first, then prompt/text inputs, then others
+    return params.sort((a, b) => {
+        if (a.required !== b.required)
+            return a.required ? -1 : 1;
+        if (a.name === 'prompt')
+            return -1;
+        if (b.name === 'prompt')
+            return 1;
+        return a.name.localeCompare(b.name);
+    });
+}
+/**
+ * Parse OpenAPI schema to determine the output URL path.
+ * Returns a path like "images[0].url", "video.url", "audio.url", etc.
+ */
+function parseOpenAPIOutputPath(schema, outputType) {
+    const schemas = schema.components?.schemas;
+    const outputSchema = findOutputSchema(schemas);
+    if (!outputSchema?.properties) {
+        return null;
+    }
+    const props = outputSchema.properties;
+    // Check for common output patterns based on output type
+    if (outputType === 'image') {
+        // Array patterns: images, outputs
+        if (props.images?.type === 'array')
+            return 'images[0].url';
+        if (props.outputs?.type === 'array')
+            return 'outputs[0].url';
+        // Object patterns: image, output
+        if (props.image)
+            return 'image.url';
+        if (props.output?.type === 'string')
+            return 'output';
+    }
+    if (outputType === 'video') {
+        // Object patterns: video
+        if (props.video)
+            return 'video.url';
+        // Array patterns: videos
+        if (props.videos?.type === 'array')
+            return 'videos[0].url';
+        if (props.output?.type === 'string')
+            return 'output';
+    }
+    if (outputType === 'audio') {
+        // Object patterns: audio, audio_file
+        if (props.audio)
+            return 'audio.url';
+        if (props.audio_file)
+            return 'audio_file.url';
+        // String patterns: audio_url
+        if (props.audio_url?.type === 'string')
+            return 'audio_url';
+        if (props.output?.type === 'string')
+            return 'output';
+    }
+    // Fallback: check for generic url property
+    if (props.url?.type === 'string')
+        return 'url';
+    return null;
+}
+/**
+ * Determine output type from fal.ai category string
+ */
+function getOutputTypeFromCategory(category) {
+    if (!category)
+        return 'image';
+    const catLower = category.toLowerCase();
+    if (catLower.includes('video'))
+        return 'video';
+    if (catLower.includes('audio') || catLower.includes('speech'))
+        return 'audio';
+    return 'image';
+}
+// =============================================================================
 // Node Definition
 // =============================================================================
 const definition = (0, types_1.defineNode)({
@@ -16,6 +189,7 @@ const definition = (0, types_1.defineNode)({
         modelId: '',
         modelName: '',
         outputType: 'image',
+        outputUrlPath: null,
         inputParams: [],
         apiKey: undefined,
         outputMode: 'per-input',

package/dist/automations/nodes/if.d.ts

@@ -1,4 +1,4 @@
-import type { NodePort, PortValue } from '../types';
+import type { NodePort, PortValue, FlowControlOutput } from '../types';
 import { type OutputMode } from './types';
 /**
  * If node inputs: dynamic boolean condition inputs + passthrough inputs.
@@ -25,6 +25,7 @@ declare const definition: import("./types").NodeDefinition<"generator", {
 declare const _default: typeof definition & {
     __TInputs: IfNodeInputs;
     __TOutputs: IfNodeOutputs;
+    __TExecutorOutput: FlowControlOutput;
 };
 export default _default;
 export { IfLogicOperators };

package/dist/automations/nodes/index.d.ts

@@ -65,6 +65,7 @@ export declare const nodeDefinitions: {
     }, import("./branch").BranchNodeInputs, import("./branch").BranchNodeOutputs, false> & {
         __TInputs: import("./branch").BranchNodeInputs;
         __TOutputs: import("./branch").BranchNodeOutputs;
+        __TExecutorOutput: import("../types").FlowControlOutput;
     };
     readonly collect: NodeDefinition<"generator", {
         expectedCount: number | undefined;
@@ -120,6 +121,7 @@ export declare const nodeDefinitions: {
         modelId: string;
         modelName: string;
         outputType: import("./custom-model").CustomModelOutputType;
+        outputUrlPath: string | null;
         inputParams: import("./custom-model").CustomModelInputParam[];
         apiKey: string | undefined;
         outputMode: import("./types").OutputMode;
@@ -186,6 +188,7 @@ export declare const nodeDefinitions: {
     }, import("./if").IfNodeInputs, import("./if").IfNodeOutputs, false> & {
         __TInputs: import("./if").IfNodeInputs;
         __TOutputs: import("./if").IfNodeOutputs;
+        __TExecutorOutput: import("../types").FlowControlOutput;
     };
     readonly 'image-composer': NodeDefinition<"generator", {
         imageEditor: {
@@ -270,6 +273,7 @@ export declare const nodeDefinitions: {
     }, import("./random-route").RandomRouteNodeInputs, import("./random-route").RandomRouteNodeOutputs, false> & {
         __TInputs: import("./random-route").RandomRouteNodeInputs;
         __TOutputs: import("./random-route").RandomRouteNodeOutputs;
+        __TExecutorOutput: import("../types").FlowControlOutput;
     };
     readonly recurrence: NodeDefinition<"trigger", {
         frequencyType: "per-day" | "periodic";
@@ -382,6 +386,10 @@ type InputsOf<T> = T extends {
 type OutputsOf<T> = T extends {
     __TOutputs: infer O;
 } ? O : never;
+/** Helper to extract executor output types from node definitions (falls back to __TOutputs) */
+type ExecutorOutputsOf<T> = T extends {
+    __TExecutorOutput: infer E;
+} ? E : OutputsOf<T>;
 /**
  * Input type lookup by node ID.
  * Auto-derived from phantom types on node definitions.
@@ -400,6 +408,16 @@ export type NodeInputs = {
 export type NodeOutputs = {
     [K in UserCreatableNodeType]: OutputsOf<(typeof nodeDefinitions)[K]>;
 };
+/**
+ * Executor output type lookup by node ID.
+ * Auto-derived from __TExecutorOutput phantom type, falls back to __TOutputs.
+ * Flow control nodes (branch, random-route, if) return FlowControlOutput.
+ * @example ExecutorOutputs['branch'] // FlowControlOutput
+ * @example ExecutorOutputs['llm'] // Record<string, PortValue | PortValue[]>
+ */
+export type ExecutorOutputs = {
+    [K in UserCreatableNodeType]: ExecutorOutputsOf<(typeof nodeDefinitions)[K]>;
+};
 export { internalNodeTypes, type InternalNodeType };
 export type { NodeDefinition } from './types';
 /** Union of all node definition types */

package/dist/automations/nodes/random-route.d.ts

@@ -1,4 +1,4 @@
-import type { NodePort, PortValue } from '../types';
+import type { NodePort, PortValue, FlowControlOutput } from '../types';
 import { type InputType, type OutputMode } from './types';
 /** Random route inputs are dynamic (passthrough inputs where inputType='variable'). */
 export type RandomRouteNodeInputs = Record<string, PortValue | PortValue[]>;
@@ -21,6 +21,7 @@ declare const definition: import("./types").NodeDefinition<"generator", {
 declare const _default: typeof definition & {
     __TInputs: RandomRouteNodeInputs;
     __TOutputs: RandomRouteNodeOutputs;
+    __TExecutorOutput: FlowControlOutput;
 };
 export default _default;
 export type RandomRouteNodeConfig = typeof definition.defaults;

package/dist/automations/types.d.ts

@@ -4,7 +4,7 @@
  * 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, NodeInputs, NodeOutputs, InternalNodeType } from './nodes';
+import type { NodeType, UserCreatableNodeType, WorkflowConfig, NodeInputs, NodeOutputs, ExecutorOutputs, InternalNodeType } from './nodes';
 import type { ForEachNodeConfig, ForEachNodeInputs, ForEachNodeOutputs } from './nodes/for-each';
 /**
  * Config type for internal node types (created dynamically at runtime).
@@ -39,6 +39,18 @@ export type InternalNodeOutputs = {
  * Combined output type lookup for all node types (user-creatable + internal).
  */
 export type AllNodeOutputs = NodeOutputs & InternalNodeOutputs;
+/**
+ * Executor output type for internal node types.
+ * for-each-value uses the same executor outputs as for-each (its parent node).
+ */
+export type InternalExecutorOutputs = {
+    'for-each-value': ForEachNodeOutputs;
+};
+/**
+ * Combined executor output type lookup for all node types (user-creatable + internal).
+ * Used by NodeExecutor to determine the return type of execute().
+ */
+export type AllExecutorOutputs = ExecutorOutputs & InternalExecutorOutputs;
 /**
  * Media type for automation nodes
  */
@@ -397,7 +409,7 @@ export interface ExecutorContext<TType extends NodeType = NodeType> {
  * Executor for synchronous nodes.
  * Generic on node type - config type is automatically derived.
  */
-export interface NodeExecutor<TType extends NodeType, TOutput = AllNodeOutputs[TType]> {
+export interface NodeExecutor<TType extends NodeType, TOutput = AllExecutorOutputs[TType]> {
     type: TType;
     /**
      * Execute the node and return a single output value.
@@ -421,7 +433,7 @@ export type ExecutorAsyncJobStatus<TOutput = unknown> = {
  * Executor for asynchronous nodes (video-editor, generate-image, workflow).
  * Uses submit/poll pattern for durable workflows.
  */
-export interface AsyncNodeExecutor<TType extends NodeType, TOutput = AllNodeOutputs[TType]> extends Omit<NodeExecutor<TType, TOutput>, 'execute'> {
+export interface AsyncNodeExecutor<TType extends NodeType, TOutput = AllExecutorOutputs[TType]> extends Omit<NodeExecutor<TType, TOutput>, 'execute'> {
     isAsync: true;
     /** Submit job - returns job ID for polling */
     submitJob: (ctx: ExecutorContext<TType>) => Promise<{

package/dist/index.d.ts

@@ -43,7 +43,8 @@ export type { BranchNodeConfig, BranchDefinition, BranchPassthroughInput, Branch
 export type { CollectNodeConfig, CollectedValues } from './automations/nodes/collect';
 export type { ComposeWorkflowNodeConfig } from './automations/nodes/compose-workflow';
 export type { CreateDmNodeConfig, CreateDmMessage, DmPlatform, } from './automations/nodes/create-dm';
-export type { CustomModelNodeConfig, CustomModelOutputType, CustomModelInputParam, } from './automations/nodes/custom-model';
+export type { CustomModelNodeConfig, CustomModelOutputType, CustomModelInputParam, CustomModelParamType, OpenAPISchema, OpenAPIProperty, } from './automations/nodes/custom-model';
+export { mapOpenAPIType, parseOpenAPIInputs, parseOpenAPIOutputPath, getOutputTypeFromCategory, } from './automations/nodes/custom-model';
 export type { DeduplicateNodeConfig } from './automations/nodes/deduplicate';
 export type { DestructureNodeConfig, DestructureNodeInputs, DestructureNodeOutputs, DestructureSelection, IndexExpression, } from './automations/nodes/destructure';
 export { indexExpressionToIndexes, resolvePath } from './automations/nodes/destructure';

package/dist/index.js

@@ -6,7 +6,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractWorkflowConfig = exports.generateNodeName = exports.shuffleNodePreview = exports.getPreviewValue = exports.removePreviewForConnection = exports.updatePreviewMapForConnection = exports.computePreviewMap = exports.computeAllNodePreviews = exports.resolveNodePreview = exports.getWorkflowOutputSchema = exports.hasMissingTerminalError = exports.hasMissingTriggerError = exports.getPortErrorsForNode = exports.getErrorNodeIds = exports.validateWorkflow = exports.checkCrossContextViolation = exports.getForEachContext = exports.getConnectedSource = exports.cleanupStaleConnections = exports.removeNodeConnections = exports.removeConnection = exports.addConnection = exports.deriveConnections = exports.createNode = exports.getOutputSchema = exports.getNodeByType = exports.getAllNodes = exports.getInputPreviewValue = exports.computeAllNodePortsWithPreviews = exports.computeAllNodePorts = exports.computePortsWithPreviews = exports.computePortsForNode = exports.areTypesCompatible = exports.submitIMessageDmRenderJob = exports.submitInstagramDmRenderJob = exports.submitAutoCaptionRenderJob = exports.submitScreenshotAnimationRenderJob = exports.submitDeduplicationJob = exports.getRenderJobStatus = exports.submitVideoRenderJob = exports.submitImageRenderJob = exports.CommentsClient = exports.MediaClient = exports.AutomationsClient = exports.OrganizationClient = exports.StatsClient = exports.PostsClient = exports.TasksClient = exports.AccountsClient = exports.UGCClient = void 0;
-exports.prepareVideoComposerInput = exports.LLMProviders = exports.IfLogicOperators = exports.resolvePath = exports.indexExpressionToIndexes = exports.nodeConfigToCaptionStyle = exports.prepareImageComposerInput = exports.processTemplate = exports.extractTemplateVariables = exports.PortIdSchema = exports.normalizeToPortId = exports.portIdToTitle = exports.isValidPortId = exports.portId = exports.selectFromPool = exports.getModelDurations = exports.getModelAspectRatios = exports.ALL_VIDEO_MODELS = exports.isImageToVideoModel = exports.IMAGE_ASPECT_RATIOS = exports.ALL_IMAGE_MODELS = exports.isEditModel = exports.getNodeDefinition = exports.isPortType = exports.formatPortType = exports.isAsyncExecutor = exports.internalNodeTypes = exports.nodeDefinitions = void 0;
+exports.prepareVideoComposerInput = exports.LLMProviders = exports.IfLogicOperators = exports.resolvePath = exports.indexExpressionToIndexes = exports.getOutputTypeFromCategory = exports.parseOpenAPIOutputPath = exports.parseOpenAPIInputs = exports.mapOpenAPIType = exports.nodeConfigToCaptionStyle = exports.prepareImageComposerInput = exports.processTemplate = exports.extractTemplateVariables = exports.PortIdSchema = exports.normalizeToPortId = exports.portIdToTitle = exports.isValidPortId = exports.portId = exports.selectFromPool = exports.getModelDurations = exports.getModelAspectRatios = exports.ALL_VIDEO_MODELS = exports.isImageToVideoModel = exports.IMAGE_ASPECT_RATIOS = exports.ALL_IMAGE_MODELS = exports.isEditModel = exports.getNodeDefinition = exports.isPortType = exports.formatPortType = exports.isAsyncExecutor = exports.internalNodeTypes = exports.nodeDefinitions = void 0;
 // =============================================================================
 // Client Exports
 // =============================================================================
@@ -124,6 +124,11 @@ var image_composer_1 = require("./automations/nodes/image-composer");
 Object.defineProperty(exports, "prepareImageComposerInput", { enumerable: true, get: function () { return image_composer_1.prepareImageComposerInput; } });
 var auto_caption_1 = require("./automations/nodes/auto-caption");
 Object.defineProperty(exports, "nodeConfigToCaptionStyle", { enumerable: true, get: function () { return auto_caption_1.nodeConfigToCaptionStyle; } });
+var custom_model_1 = require("./automations/nodes/custom-model");
+Object.defineProperty(exports, "mapOpenAPIType", { enumerable: true, get: function () { return custom_model_1.mapOpenAPIType; } });
+Object.defineProperty(exports, "parseOpenAPIInputs", { enumerable: true, get: function () { return custom_model_1.parseOpenAPIInputs; } });
+Object.defineProperty(exports, "parseOpenAPIOutputPath", { enumerable: true, get: function () { return custom_model_1.parseOpenAPIOutputPath; } });
+Object.defineProperty(exports, "getOutputTypeFromCategory", { enumerable: true, get: function () { return custom_model_1.getOutputTypeFromCategory; } });
 var destructure_1 = require("./automations/nodes/destructure");
 Object.defineProperty(exports, "indexExpressionToIndexes", { enumerable: true, get: function () { return destructure_1.indexExpressionToIndexes; } });
 Object.defineProperty(exports, "resolvePath", { enumerable: true, get: function () { return destructure_1.resolvePath; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugcinc",
-  "version": "4.1.55",
+  "version": "4.1.57",
   "description": "TypeScript/JavaScript client for the UGC Inc API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",