@happyvertical/comfyui 0.74.8

package/dist/index.d.ts

@@ -0,0 +1,506 @@
+/**
+ * @happyvertical/comfyui
+ *
+ * ComfyUI API client for workflow orchestration and video generation.
+ *
+ * @example
+ * ```typescript
+ * import { ComfyUIClient, injectWorkflowParams } from '@happyvertical/comfyui';
+ *
+ * // Create client
+ * const client = new ComfyUIClient({
+ *   url: 'http://localhost:8188',
+ * });
+ *
+ * // Connect and execute workflow
+ * await client.connect();
+ *
+ * const workflow = await loadWorkflow('my-workflow.json');
+ * const modifiedWorkflow = injectWorkflowParams(workflow, {
+ *   seedImage: '3',
+ *   prompt: '6',
+ * }, {
+ *   seedImage: 'input/anchor.png',
+ *   prompt: 'professional news anchor speaking',
+ * });
+ *
+ * const result = await client.queuePrompt(modifiedWorkflow);
+ *
+ * // Wait for completion with progress updates
+ * const history = await client.waitForCompletion(result.promptId, {
+ *   onProgress: (event) => {
+ *     if (event.type === 'progress') {
+ *       console.log(`Progress: ${event.value}/${event.max}`);
+ *     }
+ *   },
+ * });
+ *
+ * // Download output
+ * const output = history.outputs['SaveVideo'];
+ * if (output?.videos?.[0]) {
+ *   const video = await client.downloadOutput(output.videos[0].filename);
+ *   fs.writeFileSync('output.mp4', video);
+ * }
+ *
+ * await client.disconnect();
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A single node in a ComfyUI workflow
+ */
+export declare interface ComfyNode {
+    /**
+     * Node class type (e.g., 'KSampler', 'LoadImage', 'SaveImage')
+     */
+    class_type: string;
+    /**
+     * Node input values
+     */
+    inputs: Record<string, unknown>;
+    /**
+     * Optional metadata
+     */
+    _meta?: {
+        title?: string;
+    };
+}
+
+/**
+ * ComfyUI client for workflow execution and management
+ *
+ * @example
+ * ```typescript
+ * import { ComfyUIClient } from '@happyvertical/comfyui';
+ *
+ * const client = new ComfyUIClient({
+ *   url: 'http://localhost:8188',
+ * });
+ *
+ * await client.connect();
+ *
+ * const result = await client.queuePrompt(workflow);
+ * await client.waitForCompletion(result.promptId, {
+ *   onProgress: (event) => console.log(`Progress: ${event.value}%`),
+ * });
+ *
+ * const output = await client.downloadOutput('video.mp4');
+ * await client.disconnect();
+ * ```
+ */
+export declare class ComfyUIClient {
+    private options;
+    private ws;
+    private logger;
+    private clientId;
+    private messageHandlers;
+    private reconnectAttempts;
+    private isConnecting;
+    private username?;
+    private password?;
+    constructor(options?: ComfyUIClientOptions);
+    /**
+     * Get the HTTP base URL
+     */
+    private get httpUrl();
+    /**
+     * Get the WebSocket URL
+     */
+    private get wsUrl();
+    /**
+     * Connect to the ComfyUI WebSocket
+     */
+    connect(): Promise<void>;
+    /**
+     * Establish WebSocket connection
+     */
+    private establishConnection;
+    /**
+     * Handle WebSocket disconnection
+     */
+    private handleDisconnect;
+    /**
+     * Handle incoming WebSocket messages
+     */
+    private handleMessage;
+    /**
+     * Parse a WebSocket message into a ProgressEvent
+     */
+    private parseProgressEvent;
+    /**
+     * Disconnect from ComfyUI
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Make an HTTP request to ComfyUI
+     */
+    private request;
+    /**
+     * Queue a workflow for execution
+     *
+     * @param workflow - The ComfyUI workflow to execute
+     * @param clientId - Optional client ID (uses default if not provided)
+     * @returns Promise resolving to prompt result with ID
+     */
+    queuePrompt(workflow: ComfyWorkflow, clientId?: string): Promise<PromptResult>;
+    /**
+     * Subscribe to progress events for a prompt
+     *
+     * @param promptId - The prompt ID to monitor
+     * @param handler - Callback for progress events
+     * @returns Unsubscribe function
+     */
+    onProgress(promptId: string, handler: (event: ProgressEvent_2) => void): () => void;
+    /**
+     * Wait for a prompt to complete
+     *
+     * @param promptId - The prompt ID to wait for
+     * @param options - Wait options including progress callback
+     * @returns Promise resolving to the history entry
+     */
+    waitForCompletion(promptId: string, options?: WaitOptions): Promise<HistoryEntry>;
+    /**
+     * Get history for a specific prompt
+     *
+     * @param promptId - The prompt ID to get history for
+     * @returns Promise resolving to the history entry
+     */
+    getHistory(promptId: string): Promise<HistoryEntry>;
+    /**
+     * Download an output file from ComfyUI
+     *
+     * @param filename - Name of the file to download
+     * @param subfolder - Subfolder where file is located
+     * @param type - Type of file location ('output', 'temp', or 'input')
+     * @returns Promise resolving to the file buffer
+     */
+    downloadOutput(filename: string, subfolder?: string, type?: 'output' | 'temp' | 'input'): Promise<Buffer>;
+    /**
+     * Upload a file to ComfyUI
+     *
+     * @param file - File buffer to upload
+     * @param filename - Name for the file
+     * @param type - Where to upload ('input' or 'temp')
+     * @param overwrite - Whether to overwrite existing file
+     * @returns Promise resolving to upload result
+     */
+    uploadFile(file: Buffer, filename: string, type?: 'input' | 'temp', overwrite?: boolean): Promise<UploadResult>;
+    /**
+     * Get system statistics from ComfyUI
+     *
+     * @returns Promise resolving to system stats
+     */
+    getSystemStats(): Promise<SystemStats>;
+    /**
+     * Get the current queue status
+     *
+     * @returns Promise resolving to queue status
+     */
+    getQueue(): Promise<QueueStatus>;
+    /**
+     * Interrupt the current execution
+     */
+    interrupt(): Promise<void>;
+    /**
+     * Clear the execution queue
+     */
+    clearQueue(): Promise<void>;
+    /**
+     * Delete a specific item from the queue
+     *
+     * @param promptId - The prompt ID to delete
+     */
+    deleteFromQueue(promptId: string): Promise<void>;
+}
+
+/**
+ * Configuration for the ComfyUI client
+ */
+export declare interface ComfyUIClientOptions {
+    /**
+     * Base URL for the ComfyUI server
+     * @default 'http://localhost:8188'
+     */
+    url?: string;
+    /**
+     * Request timeout in milliseconds
+     * @default 600000 (10 minutes)
+     */
+    timeout?: number;
+    /**
+     * Custom headers for API requests
+     */
+    headers?: Record<string, string>;
+    /**
+     * Reconnection options for WebSocket
+     */
+    reconnect?: Partial<ReconnectOptions>;
+    /**
+     * Username for HTTP Basic authentication
+     */
+    username?: string;
+    /**
+     * Password for HTTP Basic authentication
+     */
+    password?: string;
+}
+
+/**
+ * ComfyUI workflow definition (API format JSON)
+ */
+export declare interface ComfyWorkflow {
+    /**
+     * Node definitions in the workflow
+     * Keys are node IDs
+     */
+    [nodeId: string]: ComfyNode;
+}
+
+/**
+ * History entry for a completed prompt
+ */
+export declare interface HistoryEntry {
+    /**
+     * Prompt ID
+     */
+    promptId: string;
+    /**
+     * Status of the execution
+     */
+    status: {
+        completed: boolean;
+        status_str: string;
+        messages: Array<[string, unknown]>;
+    };
+    /**
+     * Output data from each node
+     */
+    outputs: Record<string, NodeOutput>;
+    /**
+     * Original prompt data
+     */
+    prompt: [number, string, ComfyWorkflow, any, string[]];
+}
+
+/**
+ * Helper function to inject parameters into a workflow
+ *
+ * @param workflow - The base workflow
+ * @param mapping - Node mapping defining where to inject
+ * @param values - Values to inject
+ * @returns Modified workflow with injected values
+ */
+export declare function injectWorkflowParams(workflow: ComfyWorkflow, mapping: NodeMapping, values: Record<string, any>): ComfyWorkflow;
+
+/**
+ * Node mapping for dynamic parameter injection
+ */
+export declare interface NodeMapping {
+    /**
+     * Node ID for seed image input
+     */
+    seedImage?: string;
+    /**
+     * Node ID for audio file input
+     */
+    audioFile?: string;
+    /**
+     * Node ID for base video input
+     */
+    baseVideo?: string;
+    /**
+     * Node ID for final output
+     */
+    outputVideo?: string;
+    /**
+     * Node ID for text prompt input
+     */
+    prompt?: string;
+    /**
+     * Node ID for negative prompt input
+     */
+    negativePrompt?: string;
+    /**
+     * Additional custom mappings
+     */
+    [key: string]: string | undefined;
+}
+
+/**
+ * Output data from a single node
+ */
+export declare interface NodeOutput {
+    /**
+     * Images produced by this node
+     */
+    images?: Array<{
+        filename: string;
+        subfolder: string;
+        type: 'output' | 'temp' | 'input';
+    }>;
+    /**
+     * Other output data
+     */
+    [key: string]: unknown;
+}
+
+/**
+ * Progress event during workflow execution
+ */
+declare interface ProgressEvent_2 {
+    /**
+     * Type of progress event
+     */
+    type: 'executing' | 'progress' | 'execution_cached' | 'executed' | 'execution_error';
+    /**
+     * Currently executing node ID
+     */
+    nodeId?: string;
+    /**
+     * Progress value (0-100 for 'progress' type)
+     */
+    value?: number;
+    /**
+     * Maximum value for progress
+     */
+    max?: number;
+    /**
+     * Prompt ID this event relates to
+     */
+    promptId?: string;
+    /**
+     * Output data for completed nodes
+     */
+    output?: Record<string, unknown>;
+    /**
+     * Error message (for 'execution_error' type)
+     */
+    error?: string;
+}
+export { ProgressEvent_2 as ProgressEvent }
+
+/**
+ * Result from queueing a prompt
+ */
+export declare interface PromptResult {
+    /**
+     * Unique ID for this prompt execution
+     */
+    promptId: string;
+    /**
+     * Queue number position
+     */
+    number: number;
+    /**
+     * Node-specific errors (if any)
+     */
+    nodeErrors?: Record<string, string[]>;
+}
+
+/**
+ * Queue status from ComfyUI
+ */
+export declare interface QueueStatus {
+    /**
+     * Currently running prompts
+     */
+    running: Array<[number, string, ComfyWorkflow, any]>;
+    /**
+     * Pending prompts in queue
+     */
+    pending: Array<[number, string, ComfyWorkflow, any]>;
+}
+
+/**
+ * ComfyUI API Types
+ *
+ * Types for interacting with ComfyUI's REST and WebSocket APIs.
+ */
+/**
+ * Reconnection options for WebSocket
+ */
+declare interface ReconnectOptions {
+    /**
+     * Whether to automatically reconnect
+     * @default true
+     */
+    enabled: boolean;
+    /**
+     * Maximum number of reconnection attempts
+     * @default 5
+     */
+    maxAttempts: number;
+    /**
+     * Delay between reconnection attempts in ms
+     * @default 1000
+     */
+    delay: number;
+}
+
+/**
+ * System information from ComfyUI
+ */
+export declare interface SystemStats {
+    /**
+     * Available CUDA devices
+     */
+    devices: Array<{
+        name: string;
+        type: string;
+        index: number;
+        vram_total: number;
+        vram_free: number;
+        torch_vram_total: number;
+        torch_vram_free: number;
+    }>;
+    /**
+     * System RAM information
+     */
+    system: {
+        os: string;
+        python_version: string;
+        embedded_python: boolean;
+    };
+}
+
+/**
+ * File upload result
+ */
+export declare interface UploadResult {
+    /**
+     * Name of the uploaded file
+     */
+    name: string;
+    /**
+     * Subfolder where file was uploaded
+     */
+    subfolder: string;
+    /**
+     * Type of upload location
+     */
+    type: 'input' | 'temp' | 'output';
+}
+
+/**
+ * Options for waiting on prompt completion
+ */
+export declare interface WaitOptions {
+    /**
+     * Callback for progress updates
+     */
+    onProgress?: (event: ProgressEvent_2) => void;
+    /**
+     * Timeout in milliseconds (0 = no timeout)
+     * @default 600000 (10 minutes)
+     */
+    timeout?: number;
+    /**
+     * Polling interval for fallback HTTP polling (if WebSocket fails)
+     * @default 1000
+     */
+    pollInterval?: number;
+}
+
+export { }