ugcinc 4.0.2 → 4.1.1

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

@@ -0,0 +1,202 @@
+/**
+ * Node Definition Types
+ *
+ * This file contains shared types for node definitions.
+ * Each node file imports from here and defines its behavior.
+ */
+import type { NodePort, BasePortType } from '../types';
+import type { AutomationsClient } from '../index';
+/** Return type for computePorts - can be sync or async */
+export type ComputePortsResult = {
+    inputs: NodePort[];
+    outputs: NodePort[];
+};
+export type NodeCategory = 'trigger' | 'source' | 'generator' | 'terminal';
+export type OutputMode = 'per-input' | 'single';
+export type SelectionMode = 'random' | 'sequential';
+export type ExhaustionBehavior = 'restart' | 'error';
+export type InputType = 'static' | 'variable';
+/** All possible media item types */
+export type MediaItemType = 'image' | 'video' | 'audio' | 'text' | 'social_audio';
+/** Media types that can be selected from the media node */
+export type MediaNodeSelectionType = 'image' | 'video' | 'audio';
+type PrimitiveType = 'string' | 'number' | 'boolean';
+/**
+ * Generic type for object schema fields with compile-time depth enforcement.
+ *
+ * - Level 1 (default): Can have 'object' or 'array' types, arrays can contain objects
+ * - Level 2: Can have 'object' or 'array' types, arrays cannot contain objects
+ * - Level 3: Only primitive types allowed
+ *
+ * @example
+ * // Level 1 field (top-level)
+ * const field: SchemaField = { name: 'users', type: 'array', items: 'object', objectSchema: [...] };
+ *
+ * // Level 2 field (inside objectSchema)
+ * const nested: SchemaField<true, false> = { name: 'tags', type: 'array', items: 'string' };
+ *
+ * // Level 3 field (deepest level)
+ * const leaf: SchemaField<false, false> = { name: 'id', type: 'string' };
+ */
+/**
+ * Schema field type with compile-time depth enforcement for array items.
+ *
+ * - Level 1 (default): Arrays can contain objects (`items: 'object'`)
+ * - Level 2+: Arrays can only contain primitives
+ *
+ * The `objectSchema` property is always `ObjectSchemaField[]` so it can be
+ * passed directly to ports without type mismatches.
+ */
+export type SchemaField<CanNestObjects extends boolean = true> = {
+    name: string;
+    description?: string;
+    type: PrimitiveType | 'object' | 'array';
+    items?: PrimitiveType | (CanNestObjects extends true ? 'object' : never);
+    objectSchema?: ObjectSchemaField[];
+    length?: number;
+    minLength?: number;
+    maxLength?: number;
+    required?: boolean;
+};
+/** Top-level schema field - arrays can contain objects */
+export type ObjectSchemaField = SchemaField<true>;
+/** Nested schema field (inside objectSchema) - arrays can only contain primitives */
+export type NestedSchemaField = SchemaField<false>;
+export interface SelectionConfig {
+    mode?: SelectionMode;
+    enforceUniqueness?: boolean;
+    exhaustionBehavior?: ExhaustionBehavior;
+}
+export interface SelectionState {
+    usedIndices: number[];
+    currentIndex: number;
+}
+/**
+ * Iteration mode for trigger nodes with account iteration
+ * - 'fan-out': Spawn all runs simultaneously (one per account)
+ * - 'sequential': One account per trigger fire, cycling through the collection
+ */
+export type TriggerIterationMode = 'fan-out' | 'sequential';
+/**
+ * Behavior when sequential iteration exhausts all accounts
+ * - 'repeat': Start from the beginning of the collection
+ * - 'stop': Stop the automation (disable schedule for recurrence)
+ */
+export type IterationExhaustionBehavior = 'repeat' | 'stop';
+/**
+ * Selection mode for collection inputs
+ * - 'specific': Use hardcoded IDs configured at design time
+ * - 'by-tag': Query items by tag at runtime (allows dynamic collections)
+ */
+export type CollectionSelectionMode = 'specific' | 'by-tag';
+/**
+ * Account iteration configuration for trigger nodes
+ * When enabled, the trigger iterates over a collection of accounts
+ */
+export interface TriggerCollectionConfig {
+    /** Whether account iteration is enabled */
+    enabled: boolean;
+    /** Selection mode: 'specific' uses accountIds, 'by-tag' queries at runtime */
+    selectionMode?: CollectionSelectionMode;
+    /** Account IDs to iterate over (used when selectionMode is 'specific' or undefined) */
+    accountIds?: string[];
+    /** Tag to query accounts by at runtime (used when selectionMode is 'by-tag') */
+    accountTag?: string;
+}
+/**
+ * Computes the required outputMode/selectionMode types based on node category.
+ * - trigger/terminal: both null
+ * - generator: outputMode required, selectionMode null
+ * - source: both required
+ */
+type DefaultsForCategory<T extends NodeCategory, TCustom extends Record<string, unknown>> = T extends 'source' ? TCustom & {
+    outputMode: OutputMode;
+    selectionMode: SelectionMode;
+} : T extends 'generator' ? TCustom & {
+    outputMode: OutputMode;
+    selectionMode: null;
+} : TCustom & {
+    outputMode: null;
+    selectionMode: null;
+};
+/**
+ * Computes the outputModes array type based on node category.
+ */
+type OutputModesForCategory<T extends NodeCategory> = T extends 'source' | 'generator' ? OutputMode[] : null;
+/**
+ * Computes the selectionModes array type based on node category.
+ */
+type SelectionModesForCategory<T extends NodeCategory> = T extends 'source' ? SelectionMode[] : null;
+/**
+ * Resolved preview data for a node.
+ * Contains render-ready configuration with all references resolved.
+ */
+export interface ResolvedPreview {
+    /** Render-ready config (varies by node type) */
+    renderConfig: unknown;
+    /** Source URLs keyed by segment/element ID */
+    sources: Record<string, string>;
+    /** Text content keyed by segment/element ID */
+    textContent: Record<string, string>;
+}
+export interface NodeDefinition<T extends NodeCategory = NodeCategory, TDefaults extends Record<string, unknown> = Record<string, unknown>, TInternal extends boolean = false> {
+    nodeId: string;
+    label: string;
+    description: string;
+    type: T;
+    category: string;
+    /** If true, this node is internal and not user-creatable */
+    isInternal: TInternal;
+    outputModes: OutputModesForCategory<T>;
+    selectionModes: SelectionModesForCategory<T>;
+    defaults: DefaultsForCategory<T, TDefaults>;
+    computePorts: (params: {
+        config: DefaultsForCategory<T, TDefaults>;
+        client?: AutomationsClient;
+        getConnectedOutput?: (inputId: string) => {
+            type: BasePortType | BasePortType[];
+            isArray: boolean;
+            objectSchema?: ObjectSchemaField[];
+        } | null;
+    }) => ComputePortsResult | Promise<ComputePortsResult>;
+    /**
+     * Resolve preview values for this node.
+     * Converts config with refs (inputId/textInputId) to render-ready format.
+     * Only implemented by nodes that support preview (image-composer, video-composer).
+     */
+    resolvePreview?: (config: DefaultsForCategory<T, TDefaults>) => ResolvedPreview | null;
+}
+/**
+ * Define a node with full type inference.
+ *
+ * - outputMode/selectionMode in defaults are typed based on the node's `type`
+ * - Custom defaults are merged and available in computePorts
+ * - No manual type assertions needed
+ */
+export declare function defineNode<T extends NodeCategory, TCustomDefaults extends Record<string, unknown>, TInternal extends boolean = false>(def: {
+    nodeId: string;
+    label: string;
+    description: string;
+    type: T;
+    category: string;
+    /** If true, this node is internal and not user-creatable */
+    isInternal?: TInternal;
+    outputModes: OutputModesForCategory<T>;
+    selectionModes: SelectionModesForCategory<T>;
+    defaults: DefaultsForCategory<T, TCustomDefaults>;
+    computePorts: (params: {
+        config: DefaultsForCategory<T, TCustomDefaults>;
+        client?: AutomationsClient;
+        getConnectedOutput?: (inputId: string) => {
+            type: BasePortType | BasePortType[];
+            isArray: boolean;
+            objectSchema?: ObjectSchemaField[];
+        } | null;
+    }) => ComputePortsResult | Promise<ComputePortsResult>;
+    /**
+     * Resolve preview values for this node.
+     * Converts config with refs (inputId/textInputId) to render-ready format.
+     */
+    resolvePreview?: (config: DefaultsForCategory<T, TCustomDefaults>) => ResolvedPreview | null;
+}): NodeDefinition<T, TCustomDefaults, TInternal>;
+export {};

package/dist/automations/nodes/types.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Node Definition Types
+ *
+ * This file contains shared types for node definitions.
+ * Each node file imports from here and defines its behavior.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineNode = defineNode;
+// =============================================================================
+// Helper Function
+// =============================================================================
+/**
+ * Define a node with full type inference.
+ *
+ * - outputMode/selectionMode in defaults are typed based on the node's `type`
+ * - Custom defaults are merged and available in computePorts
+ * - No manual type assertions needed
+ */
+function defineNode(def) {
+    return { ...def, isInternal: (def.isInternal ?? false) };
+}

package/dist/automations/nodes/video-composer.d.ts

@@ -0,0 +1,16 @@
+declare const definition: import("./types").NodeDefinition<"generator", {
+    videoEditor: {
+        width: number;
+        height: number;
+        fps: number;
+        dimensionPreset: string;
+        channels: {
+            id: string;
+            name: string;
+            segments: never[];
+        }[];
+    };
+    outputMode: "per-input";
+    selectionMode: null;
+}, false>;
+export default definition;

package/dist/automations/nodes/video-composer.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const types_1 = require("./types");
+const definition = (0, types_1.defineNode)({
+    nodeId: 'video-composer',
+    label: 'Video Composer',
+    description: 'Create templated videos',
+    type: 'generator',
+    category: 'Generation',
+    outputModes: ['per-input', 'single'],
+    selectionModes: null,
+    defaults: {
+        videoEditor: {
+            width: 1080,
+            height: 1920,
+            fps: 30,
+            dimensionPreset: '9:16',
+            channels: [{
+                    id: 'main-track',
+                    name: 'Main Track',
+                    segments: [],
+                }],
+        },
+        outputMode: 'per-input',
+        selectionMode: null,
+    },
+    computePorts: ({ config }) => {
+        const editorConfig = config?.videoEditor;
+        const inputs = [];
+        const addedIds = new Set();
+        if (editorConfig) {
+            editorConfig.channels.forEach(channel => {
+                channel.segments.forEach(segment => {
+                    // inputRef exists on all segments except 'text'
+                    if (segment.type !== 'text') {
+                        if (segment.inputRef && !addedIds.has(segment.inputRef)) {
+                            addedIds.add(segment.inputRef);
+                            const inputType = segment.type === 'video' || segment.type === 'video-sequence' ? 'video'
+                                : segment.type === 'audio' ? 'audio'
+                                    : 'image';
+                            inputs.push({
+                                id: segment.inputRef,
+                                type: inputType,
+                                isArray: segment.type === 'image-sequence' || segment.type === 'video-sequence',
+                                required: segment.required ?? true,
+                            });
+                        }
+                    }
+                    // textInputRef only exists on 'text' segments
+                    if (segment.type === 'text') {
+                        if (segment.textInputRef && !addedIds.has(segment.textInputRef)) {
+                            addedIds.add(segment.textInputRef);
+                            inputs.push({
+                                id: segment.textInputRef,
+                                type: 'text',
+                                isArray: false,
+                                required: segment.required ?? true,
+                            });
+                        }
+                    }
+                });
+            });
+        }
+        return {
+            inputs,
+            outputs: [
+                {
+                    id: 'output',
+                    type: 'video',
+                    isArray: false,
+                    required: true,
+                },
+            ],
+        };
+    },
+    resolvePreview: (config) => {
+        const editorConfig = config?.videoEditor;
+        if (!editorConfig)
+            return null;
+        const sources = {};
+        const textContent = {};
+        // Resolve segments: inputRef/textInputRef -> segment.id
+        for (const channel of editorConfig.channels) {
+            for (const segment of channel.segments) {
+                if (segment.type !== 'text') {
+                    // Media segments with inputRef
+                    if (segment.inputRef) {
+                        const url = editorConfig.previewUrls?.[segment.inputRef];
+                        if (url) {
+                            sources[segment.id] = url;
+                        }
+                    }
+                }
+                else {
+                    // Text segments with textInputRef
+                    if (segment.textInputRef) {
+                        const text = editorConfig.previewTextValues?.[segment.textInputRef];
+                        if (text) {
+                            textContent[segment.id] = text;
+                        }
+                    }
+                }
+            }
+        }
+        return {
+            renderConfig: {
+                width: editorConfig.width,
+                height: editorConfig.height,
+                fps: editorConfig.fps,
+                channels: editorConfig.channels,
+            },
+            sources,
+            textContent,
+        };
+    },
+});
+exports.default = definition;

package/dist/automations/nodes/video-import.d.ts

@@ -0,0 +1,9 @@
+export type VideoImportPlatform = 'youtube' | 'tiktok' | 'instagram';
+export type VideoImportQuality = '360' | '480' | '720' | '1080' | '1440' | '2160';
+declare const definition: import("./types").NodeDefinition<"source", {
+    platform: VideoImportPlatform;
+    videoQuality: VideoImportQuality;
+    outputMode: "per-input";
+    selectionMode: "random";
+}, false>;
+export default definition;

package/dist/automations/nodes/video-import.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const types_1 = require("./types");
+const definition = (0, types_1.defineNode)({
+    nodeId: 'video-import',
+    label: 'Import Video',
+    description: 'Import videos from YouTube, TikTok, Instagram & more',
+    type: 'source',
+    category: 'Sources',
+    outputModes: ['per-input', 'single'],
+    selectionModes: ['random', 'sequential'],
+    defaults: {
+        platform: 'youtube',
+        videoQuality: '1080',
+        outputMode: 'per-input',
+        selectionMode: 'random',
+    },
+    computePorts: () => ({
+        inputs: [{ id: 'url', type: 'text', isArray: false, required: true }],
+        outputs: [{ id: 'video', type: 'video', isArray: false, required: true }],
+    }),
+});
+exports.default = definition;