@runtypelabs/sdk 0.1.1

package/dist/flows-namespace.js

@@ -0,0 +1,679 @@
+"use strict";
+/**
+ * FlowsNamespace - Static namespace for flow operations
+ *
+ * Provides factory methods for creating flow builders with different modes:
+ * - upsert: Create or update a flow by name
+ * - virtual: One-off execution without saving
+ * - use: Execute an existing flow by ID
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntypeFlowBuilder = exports.FlowsNamespace = void 0;
+const flow_result_1 = require("./flow-result");
+// ============================================================================
+// FlowsNamespace
+// ============================================================================
+class FlowsNamespace {
+    constructor(getClient) {
+        this.getClient = getClient;
+    }
+    /**
+     * Create or update a flow by name (upsert mode)
+     *
+     * The recommended pattern for code-first flow management.
+     * Creates the flow if it doesn't exist, updates if steps changed.
+     *
+     * @example
+     * ```typescript
+     * const result = await Runtype.flows.upsert({
+     *   name: 'My Flow',
+     *   createVersionOnChange: true
+     * })
+     *   .prompt({ name: 'Analyze', model: 'gpt-4o', userPrompt: '...' })
+     *   .stream()
+     * ```
+     */
+    upsert(config) {
+        return new RuntypeFlowBuilder(this.getClient, 'upsert', config);
+    }
+    /**
+     * Create a virtual flow (one-off, not saved)
+     *
+     * Use for temporary or ad-hoc flow execution.
+     *
+     * @example
+     * ```typescript
+     * const result = await Runtype.flows.virtual({ name: 'Temp Flow' })
+     *   .prompt({ name: 'Process', model: 'gpt-4o', userPrompt: '...' })
+     *   .stream()
+     * ```
+     */
+    virtual(config) {
+        return new RuntypeFlowBuilder(this.getClient, 'virtual', config);
+    }
+    /**
+     * Use an existing flow by ID
+     *
+     * @example
+     * ```typescript
+     * const result = await Runtype.flows.use('flow_123')
+     *   .withRecord({ name: 'Test', type: 'data' })
+     *   .stream()
+     * ```
+     */
+    use(flowId) {
+        return new RuntypeFlowBuilder(this.getClient, 'existing', undefined, flowId);
+    }
+    /**
+     * Quick execution of an existing flow
+     *
+     * @example
+     * ```typescript
+     * const result = await Runtype.flows.execute('flow_123', {
+     *   record: { name: 'Test', type: 'data' },
+     *   streamResponse: true
+     * })
+     * ```
+     */
+    async execute(flowId, options) {
+        const builder = this.use(flowId);
+        if (options?.record)
+            builder.withRecord(options.record);
+        if (options?.messages)
+            builder.withMessages(options.messages);
+        return options?.streamResponse !== false ? builder.stream() : builder.result();
+    }
+}
+exports.FlowsNamespace = FlowsNamespace;
+// ============================================================================
+// RuntypeFlowBuilder
+// ============================================================================
+/**
+ * Fluent builder for constructing and executing flows
+ */
+class RuntypeFlowBuilder {
+    constructor(getClient, mode, config, flowId) {
+        this.getClient = getClient;
+        this.steps = [];
+        this.stepCounter = 0;
+        this.upsertOptions = {};
+        this.dispatchOptions = {};
+        this.mode = mode;
+        if (mode === 'existing' && flowId) {
+            this.existingFlowId = flowId;
+            this.flowConfig = { name: '' };
+        }
+        else if (config) {
+            const { createVersionOnChange, allowOverwriteExternalChanges, ...flowConfig } = config;
+            this.flowConfig = flowConfig;
+            if (mode === 'upsert') {
+                this.upsertOptions = {
+                    createVersionOnChange: createVersionOnChange ?? true,
+                    ...(allowOverwriteExternalChanges !== undefined && { allowOverwriteExternalChanges }),
+                };
+            }
+        }
+        else {
+            this.flowConfig = { name: 'Untitled Flow' };
+        }
+    }
+    // ============================================================================
+    // Configuration Methods
+    // ============================================================================
+    /**
+     * Set the record configuration
+     */
+    withRecord(config) {
+        this.recordConfig = config;
+        return this;
+    }
+    /**
+     * Set conversation messages
+     */
+    withMessages(messages) {
+        this.messagesConfig = messages;
+        return this;
+    }
+    /**
+     * Set dispatch options
+     */
+    withOptions(options) {
+        this.dispatchOptions = { ...this.dispatchOptions, ...options };
+        return this;
+    }
+    // ============================================================================
+    // Step Methods
+    // ============================================================================
+    /**
+     * Add a prompt step
+     */
+    prompt(config) {
+        this.addStep('prompt', config.name, {
+            model: config.model,
+            userPrompt: config.userPrompt,
+            text: config.userPrompt,
+            systemPrompt: config.systemPrompt,
+            previousMessages: config.previousMessages,
+            outputVariable: config.outputVariable,
+            responseFormat: config.responseFormat,
+            temperature: config.temperature,
+            maxTokens: config.maxTokens,
+            reasoning: config.reasoning,
+            streamOutput: config.streamOutput,
+            tools: config.tools,
+        }, config.enabled);
+        return this;
+    }
+    /**
+     * Add a fetch URL step
+     */
+    fetchUrl(config) {
+        this.addStep('fetch-url', config.name, {
+            http: {
+                url: config.url,
+                method: config.method || 'GET',
+                headers: config.headers,
+                body: config.body,
+            },
+            fetchMethod: config.fetchMethod,
+            firecrawl: config.firecrawl,
+            outputVariable: config.outputVariable,
+            errorHandling: config.errorHandling,
+            streamOutput: config.streamOutput,
+        }, config.enabled);
+        return this;
+    }
+    /**
+     * Add a transform data step
+     */
+    transformData(config) {
+        this.addStep('transform-data', config.name, {
+            script: config.script,
+            outputVariable: config.outputVariable,
+            streamOutput: config.streamOutput,
+        }, config.enabled);
+        return this;
+    }
+    /**
+     * Add a set variable step
+     */
+    setVariable(config) {
+        this.addStep('set-variable', config.name, {
+            variableName: config.variableName,
+            value: config.value,
+        }, config.enabled);
+        return this;
+    }
+    /**
+     * Add a conditional step
+     */
+    conditional(config) {
+        this.addStep('conditional', config.name, {
+            condition: config.condition,
+            trueSteps: config.trueSteps || [],
+            falseSteps: config.falseSteps || [],
+        }, config.enabled);
+        return this;
+    }
+    /**
+     * Add a search step
+     */
+    search(config) {
+        this.addStep('search', config.name, {
+            provider: config.provider,
+            query: config.query,
+            maxResults: config.maxResults,
+            outputVariable: config.outputVariable,
+            returnCitations: config.returnCitations,
+            errorHandling: config.errorHandling,
+            streamOutput: config.streamOutput,
+        }, config.enabled);
+        return this;
+    }
+    /**
+     * Add a send email step
+     */
+    sendEmail(config) {
+        this.addStep('send-email', config.name, {
+            to: config.to,
+            from: config.from || 'no-reply@messages.runtype.com',
+            subject: config.subject,
+            html: config.html,
+            outputVariable: config.outputVariable,
+            errorHandling: config.errorHandling,
+            streamOutput: config.streamOutput,
+        }, config.enabled);
+        return this;
+    }
+    /**
+     * Add a send stream step
+     */
+    sendStream(config) {
+        this.addStep('send-stream', config.name, {
+            message: config.message,
+        }, config.enabled);
+        return this;
+    }
+    /**
+     * Add a retrieve record step
+     */
+    retrieveRecord(config) {
+        this.addStep('retrieve-record', config.name, {
+            recordType: config.recordType,
+            recordName: config.recordName,
+            fieldsToInclude: config.fieldsToInclude,
+            fieldsToExclude: config.fieldsToExclude,
+            outputVariable: config.outputVariable,
+            streamOutput: config.streamOutput,
+        }, config.enabled);
+        return this;
+    }
+    /**
+     * Add an upsert record step
+     */
+    upsertRecord(config) {
+        this.addStep('upsert-record', config.name, {
+            recordType: config.recordType,
+            recordName: config.recordName,
+            sourceVariable: config.sourceVariable,
+            mergeStrategy: config.mergeStrategy,
+            outputVariable: config.outputVariable,
+            errorHandling: config.errorHandling,
+            streamOutput: config.streamOutput,
+        }, config.enabled);
+        return this;
+    }
+    /**
+     * Add a vector search step
+     */
+    vectorSearch(config) {
+        this.addStep('vector-search', config.name, {
+            query: config.query,
+            recordType: config.recordType,
+            embeddingModel: config.embeddingModel,
+            limit: config.limit,
+            threshold: config.threshold,
+            outputVariable: config.outputVariable,
+            includeDistance: config.includeDistance,
+            streamOutput: config.streamOutput,
+        }, config.enabled);
+        return this;
+    }
+    /**
+     * Add a generate embedding step
+     */
+    generateEmbedding(config) {
+        this.addStep('generate-embedding', config.name, {
+            inputSource: 'text',
+            text: config.text,
+            embeddingModel: config.embeddingModel,
+            maxLength: config.maxLength,
+            outputVariable: config.outputVariable,
+            streamOutput: config.streamOutput,
+        }, config.enabled);
+        return this;
+    }
+    /**
+     * Add a wait until step
+     */
+    waitUntil(config) {
+        this.addStep('wait-until', config.name, {
+            delayMs: config.delayMs,
+            continueOnTimeout: config.continueOnTimeout,
+            poll: config.poll,
+            outputVariable: config.outputVariable,
+            errorHandling: config.errorHandling,
+            streamOutput: config.streamOutput,
+        }, config.enabled);
+        return this;
+    }
+    /**
+     * Add a send event step
+     */
+    sendEvent(config) {
+        this.addStep('send-event', config.name, {
+            provider: config.provider,
+            eventName: config.eventName,
+            properties: config.properties,
+            outputVariable: config.outputVariable,
+            errorHandling: config.errorHandling,
+            streamOutput: config.streamOutput,
+        }, config.enabled);
+        return this;
+    }
+    /**
+     * Add a send text step
+     */
+    sendText(config) {
+        this.addStep('send-text', config.name, {
+            to: config.to,
+            from: config.from,
+            message: config.message,
+            outputVariable: config.outputVariable,
+            errorHandling: config.errorHandling,
+            streamOutput: config.streamOutput,
+        }, config.enabled);
+        return this;
+    }
+    /**
+     * Add a fetch GitHub step
+     */
+    fetchGitHub(config) {
+        this.addStep('fetch-github', config.name, {
+            repository: config.repository,
+            branch: config.branch,
+            path: config.path,
+            outputVariable: config.outputVariable,
+            streamOutput: config.streamOutput,
+        }, config.enabled);
+        return this;
+    }
+    async stream(arg1, arg2) {
+        const config = this.build();
+        let callbacks;
+        let localTools;
+        if (arg1) {
+            if ('localTools' in arg1) {
+                localTools = arg1.localTools;
+            }
+            else {
+                callbacks = arg1;
+                if (arg2) {
+                    localTools = arg2.localTools;
+                }
+            }
+        }
+        // Handle local tools if provided
+        if (localTools) {
+            return this.runWithLocalTools(localTools, callbacks);
+        }
+        config.options = { ...config.options, streamResponse: true };
+        const client = this.getClient();
+        const response = await client.dispatch(config);
+        const result = new flow_result_1.FlowResult(response);
+        // If callbacks provided, process immediately
+        if (callbacks) {
+            await result.stream(callbacks);
+        }
+        return result;
+    }
+    /**
+     * Execute the flow and wait for complete result (no streaming)
+     *
+     * Returns a FlowResult after all steps have completed.
+     *
+     * @example
+     * ```typescript
+     * const result = await Runtype.flows.use('flow_123')
+     *   .withRecord({ ... })
+     *   .result()
+     *
+     * const analysis = await result.getResult('Analyze')
+     * const allResults = await result.getAllResults()
+     * ```
+     */
+    async result(options) {
+        const config = this.build();
+        // Handle local tools if provided
+        if (options?.localTools) {
+            return this.runWithLocalTools(options.localTools);
+        }
+        config.options = { ...config.options, streamResponse: true };
+        const client = this.getClient();
+        const response = await client.dispatch(config);
+        const result = new flow_result_1.FlowResult(response);
+        // Pre-process the stream to cache results
+        await result.getSummary();
+        return result;
+    }
+    /**
+     * Execute the flow with local tools (automatic pause/resume loop)
+     *
+     * @param localTools - Map of tool names to async functions that execute the tool logic
+     * @returns The final result of the flow execution
+     */
+    async runWithLocalTools(localTools, callbacks) {
+        const config = this.build();
+        const isStreaming = !!callbacks;
+        // Force options
+        config.options = {
+            ...config.options,
+            streamResponse: isStreaming,
+        };
+        // Add stream_response snake_case too just in case
+        if (config.options) {
+            config.options.stream_response = isStreaming;
+        }
+        const client = this.getClient();
+        // Accumulated results across pause/resume cycles - moved outside processStep
+        // so results persist when flow pauses and resumes
+        const accumulatedSummary = {
+            results: new Map(),
+            success: true
+        };
+        // Helper to process a step result (either from stream or JSON)
+        const processStep = async (response) => {
+            if (isStreaming) {
+                // Stream processing
+                let pausedState = null;
+                // Wrap user callbacks to intercept paused event
+                const wrappedCallbacks = {
+                    ...callbacks,
+                    onFlowStart: (event) => callbacks?.onFlowStart?.(event),
+                    onStepStart: (event) => callbacks?.onStepStart?.(event),
+                    onStepChunk: (chunk, event) => callbacks?.onStepChunk?.(chunk, event),
+                    onStepComplete: (result, event) => callbacks?.onStepComplete?.(result, event),
+                    onFlowComplete: (event) => callbacks?.onFlowComplete?.(event),
+                    onError: (error) => callbacks?.onError?.(error)
+                };
+                // Use streamEvents from stream-utils
+                const { streamEvents } = await Promise.resolve().then(() => __importStar(require('./stream-utils')));
+                try {
+                    for await (const event of streamEvents(response)) {
+                        // Check for flow_paused
+                        if (event.type === 'flow_paused') {
+                            pausedState = {
+                                toolName: event.toolName,
+                                parameters: event.parameters,
+                                executionId: event.executionId
+                            };
+                        }
+                        if (event.type === 'step_waiting_local') {
+                            pausedState = {
+                                toolName: event.toolName,
+                                parameters: event.parameters,
+                                executionId: event.executionId
+                            };
+                        }
+                        // Handle standard events via callbacks
+                        switch (event.type) {
+                            case 'flow_start':
+                                wrappedCallbacks.onFlowStart?.(event);
+                                break;
+                            case 'step_start':
+                                wrappedCallbacks.onStepStart?.(event);
+                                break;
+                            case 'step_chunk': {
+                                // Normalize API's 'text' field to 'chunk' for consistency
+                                const chunkText = event.chunk || event.text || '';
+                                wrappedCallbacks.onStepChunk?.(chunkText, event);
+                                break;
+                            }
+                            case 'step_complete':
+                                // Accumulate results in the outer summary that persists across pause/resume
+                                accumulatedSummary.results?.set(event.name, event.result);
+                                wrappedCallbacks.onStepComplete?.(event.result, event);
+                                break;
+                            case 'flow_complete':
+                                wrappedCallbacks.onFlowComplete?.(event);
+                                break;
+                            case 'flow_error':
+                                wrappedCallbacks.onError?.(new Error(event.error));
+                                break;
+                        }
+                    }
+                }
+                catch (e) {
+                    wrappedCallbacks.onError?.(e instanceof Error ? e : new Error(String(e)));
+                    throw e;
+                }
+                if (pausedState) {
+                    return { done: false, result: { status: 'paused', pausedReason: { type: 'local_action', ...pausedState } } };
+                }
+                return { done: true, result: accumulatedSummary };
+            }
+            else {
+                // Non-streaming (JSON)
+                const data = await response.json();
+                return {
+                    done: data.status !== 'paused',
+                    result: data
+                };
+            }
+        };
+        // Initial dispatch
+        let currentResponse;
+        if (isStreaming) {
+            currentResponse = await client.dispatch(config);
+        }
+        else {
+            const data = await client.post('/dispatch', config);
+            currentResponse = new Response(JSON.stringify(data), { headers: { 'content-type': 'application/json' } });
+        }
+        // Loop
+        while (true) {
+            const { done, result } = await processStep(currentResponse);
+            if (done) {
+                if (isStreaming) {
+                    // Create FlowResult with summary
+                    const finalResponse = new Response(JSON.stringify(result), { headers: { 'content-type': 'application/json' } });
+                    return new flow_result_1.FlowResult(finalResponse, result);
+                }
+                return new flow_result_1.FlowResult(new Response(JSON.stringify(result), { headers: { 'content-type': 'application/json' } }));
+            }
+            // Handle Pause
+            if (result.status === 'paused' && result.pausedReason?.type === 'local_action') {
+                const { toolName, parameters, executionId } = result.pausedReason;
+                if (!localTools[toolName]) {
+                    throw new Error(`Local tool "${toolName}" required but not provided in localTools map`);
+                }
+                try {
+                    // Execute local tool logic
+                    const toolResult = await localTools[toolName](parameters);
+                    // Resume flow execution - API expects snake_case field names
+                    const resumeData = {
+                        execution_id: executionId,
+                        tool_outputs: { [toolName]: toolResult },
+                        stream_response: isStreaming
+                    };
+                    if (isStreaming) {
+                        currentResponse = await client.requestStream('/dispatch/resume', {
+                            method: 'POST',
+                            body: JSON.stringify(resumeData)
+                        });
+                    }
+                    else {
+                        const data = await client.post('/dispatch/resume', resumeData);
+                        currentResponse = new Response(JSON.stringify(data), { headers: { 'content-type': 'application/json' } });
+                    }
+                }
+                catch (error) {
+                    throw new Error(`Error executing local tool "${toolName}": ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            else {
+                break;
+            }
+        }
+        throw new Error('Unexpected end of flow execution loop');
+    }
+    build() {
+        const flowMode = this.mode === 'existing' ? 'existing' : this.mode;
+        const flow = this.existingFlowId
+            ? { id: this.existingFlowId }
+            : { name: this.flowConfig.name, steps: this.steps };
+        const request = { flow };
+        if (this.recordConfig) {
+            request.record = this.recordConfig;
+        }
+        if (this.messagesConfig) {
+            request.messages = this.messagesConfig;
+        }
+        const options = {
+            flowMode,
+            ...this.dispatchOptions,
+        };
+        // Auto-detect recordMode based on record config if not explicitly set
+        if (this.recordConfig && !this.dispatchOptions.recordMode) {
+            if (this.recordConfig.id) {
+                options.recordMode = 'existing';
+            }
+            else if (this.recordConfig.name || this.recordConfig.type) {
+                options.recordMode = 'create';
+            }
+            else {
+                options.recordMode = 'virtual';
+            }
+        }
+        if (this.mode === 'upsert' && Object.keys(this.upsertOptions).length > 0) {
+            options.upsertOptions = this.upsertOptions;
+        }
+        request.options = options;
+        return request;
+    }
+    // ============================================================================
+    // Private Helpers
+    // ============================================================================
+    addStep(type, name, config, enabled = true) {
+        this.stepCounter++;
+        const cleanConfig = {};
+        for (const [key, value] of Object.entries(config)) {
+            if (value !== undefined) {
+                cleanConfig[key] = value;
+            }
+        }
+        this.steps.push({
+            id: `step-${this.stepCounter}`,
+            type,
+            name,
+            order: this.stepCounter,
+            enabled,
+            config: cleanConfig,
+        });
+    }
+}
+exports.RuntypeFlowBuilder = RuntypeFlowBuilder;
+//# sourceMappingURL=flows-namespace.js.map