@runtypelabs/sdk 1.7.2 → 1.8.0

package/dist/flow-builder.d.ts

@@ -1,717 +0,0 @@
-/**
- * FlowBuilder - Fluent builder for constructing dispatch configurations
- *
- * Provides a chainable API for building flows with steps, making flow
- * construction more readable and type-safe.
- *
- * @example
- * ```typescript
- * import { FlowBuilder } from '@runtypelabs/sdk'
- *
- * const config = new FlowBuilder()
- *   .createFlow({ name: "My Flow" })
- *   .withRecord({ name: "Record", type: "data", metadata: { key: "value" } })
- *   .fetchUrl({ name: "Fetch", url: "https://api.example.com", outputVariable: "data" })
- *   .prompt({ name: "Process", model: "gpt-4", userPrompt: "Analyze: {{data}}" })
- *   .withOptions({ streamResponse: true, flowMode: "virtual" })
- *   .build()
- * ```
- */
-import type { DispatchRequest, MessageContent, ToolsConfig, RuntimeTool, ReasoningConfig } from './types';
-import type { ErrorHandlingMode, PromptErrorHandling, ContextErrorHandling } from './error-handling-types';
-import { FlowResult } from './flow-result';
-export interface PromptStepConfig {
-    name: string;
-    model: string;
-    userPrompt: string;
-    systemPrompt?: string;
-    previousMessages?: string | Array<{
-        role: string;
-        content: string;
-    }>;
-    outputVariable?: string;
-    responseFormat?: 'text' | 'json';
-    temperature?: number;
-    maxTokens?: number;
-    /**
-     * Enable reasoning/extended thinking for models that support it.
-     * - `true`: Enable with provider defaults
-     * - `ReasoningConfig`: Fine-grained control over reasoning behavior
-     *
-     * @example GPT-5 with streaming reasoning
-     * ```typescript
-     * reasoning: { enabled: true, reasoningSummary: 'auto' }
-     * ```
-     */
-    reasoning?: boolean | ReasoningConfig;
-    streamOutput?: boolean;
-    /** Tools configuration - supports saved tools (toolIds) and inline runtime tools */
-    tools?: ToolsConfig;
-    /** Error handling configuration - supports simple mode or fallback chains */
-    errorHandling?: ErrorHandlingMode | PromptErrorHandling;
-    enabled?: boolean;
-}
-export interface FetchUrlStepConfig {
-    name: string;
-    url: string;
-    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
-    headers?: Record<string, string>;
-    body?: string;
-    responseType?: 'json' | 'text' | 'xml';
-    markdownIfAvailable?: boolean;
-    outputVariable?: string;
-    fetchMethod?: 'http' | 'firecrawl';
-    firecrawl?: {
-        formats?: string[];
-        [key: string]: any;
-    };
-    /** Error handling configuration - supports simple mode or fallback chains */
-    errorHandling?: ErrorHandlingMode | ContextErrorHandling;
-    streamOutput?: boolean;
-    enabled?: boolean;
-}
-export interface TransformDataStepConfig {
-    name: string;
-    script: string;
-    outputVariable?: string;
-    sandboxProvider?: 'quickjs' | 'daytona' | 'cloudflare-worker';
-    streamOutput?: boolean;
-    enabled?: boolean;
-}
-export interface SetVariableStepConfig {
-    name: string;
-    variableName: string;
-    value: string | number | boolean | object;
-    enabled?: boolean;
-}
-export interface ConditionalStepConfig {
-    name: string;
-    condition: string;
-    trueSteps?: any[];
-    falseSteps?: any[];
-    enabled?: boolean;
-}
-export interface SearchStepConfig {
-    name: string;
-    provider: string;
-    query: string;
-    maxResults?: number;
-    outputVariable?: string;
-    returnCitations?: boolean;
-    /** Error handling configuration - supports simple mode or fallback chains */
-    errorHandling?: ErrorHandlingMode | ContextErrorHandling;
-    streamOutput?: boolean;
-    enabled?: boolean;
-}
-export interface SendEmailStepConfig {
-    name: string;
-    to: string;
-    from?: string;
-    subject: string;
-    html: string;
-    outputVariable?: string;
-    /** Error handling configuration - supports simple mode or fallback chains */
-    errorHandling?: ErrorHandlingMode | ContextErrorHandling;
-    streamOutput?: boolean;
-    enabled?: boolean;
-}
-export interface SendStreamStepConfig {
-    name: string;
-    message: string;
-    enabled?: boolean;
-}
-export interface RetrieveRecordStepConfig {
-    name: string;
-    recordType?: string;
-    recordName?: string;
-    fieldsToInclude?: string[];
-    fieldsToExclude?: string[];
-    outputVariable?: string;
-    streamOutput?: boolean;
-    enabled?: boolean;
-}
-export interface UpsertRecordStepConfig {
-    name: string;
-    recordType: string;
-    recordName?: string;
-    sourceVariable?: string;
-    mergeStrategy?: 'merge' | 'replace';
-    outputVariable?: string;
-    /** Error handling configuration - supports simple mode or fallback chains */
-    errorHandling?: ErrorHandlingMode | ContextErrorHandling;
-    streamOutput?: boolean;
-    enabled?: boolean;
-}
-export interface VectorSearchStepConfig {
-    name: string;
-    query: string;
-    recordType?: string;
-    embeddingModel?: string;
-    limit?: number;
-    threshold?: number;
-    outputVariable?: string;
-    streamOutput?: boolean;
-    enabled?: boolean;
-}
-export interface GenerateEmbeddingStepConfig {
-    name: string;
-    text: string;
-    embeddingModel?: string;
-    maxLength?: number;
-    outputVariable?: string;
-    streamOutput?: boolean;
-    enabled?: boolean;
-}
-export interface WaitUntilStepConfig {
-    name: string;
-    delayMs?: number;
-    continueOnTimeout?: boolean;
-    poll?: {
-        enabled: boolean;
-        intervalMs?: number;
-        maxAttempts?: number;
-        condition?: string;
-    };
-    outputVariable?: string;
-    /** Error handling configuration - supports simple mode or fallback chains */
-    errorHandling?: ErrorHandlingMode | ContextErrorHandling;
-    streamOutput?: boolean;
-    enabled?: boolean;
-}
-export interface SendEventStepConfig {
-    name: string;
-    provider: string;
-    eventName: string;
-    properties?: Record<string, any>;
-    outputVariable?: string;
-    /** Error handling configuration - supports simple mode or fallback chains */
-    errorHandling?: ErrorHandlingMode | ContextErrorHandling;
-    streamOutput?: boolean;
-    enabled?: boolean;
-}
-export interface SendTextStepConfig {
-    name: string;
-    to: string;
-    from?: string;
-    message: string;
-    outputVariable?: string;
-    /** Error handling configuration - supports simple mode or fallback chains */
-    errorHandling?: ErrorHandlingMode | ContextErrorHandling;
-    streamOutput?: boolean;
-    enabled?: boolean;
-}
-export interface FetchGitHubStepConfig {
-    name: string;
-    repository: string;
-    branch?: string;
-    path?: string;
-    outputVariable?: string;
-    streamOutput?: boolean;
-    enabled?: boolean;
-}
-export interface FlowConfig {
-    name: string;
-    description?: string;
-}
-/**
- * Configuration for upsert flow - includes flow name and upsert behavior options
- */
-export interface UpsertFlowConfig extends FlowConfig {
-    /** Whether to create a version snapshot before updating (default: true) */
-    createVersionOnChange?: boolean;
-    /** Allow overwriting changes made via dashboard/API (default: false) */
-    allowOverwriteExternalChanges?: boolean;
-}
-export interface RecordConfig {
-    id?: number | string;
-    name?: string;
-    type?: string;
-    metadata?: Record<string, any>;
-}
-/**
- * Options for upsert mode - controls conflict detection and versioning
- */
-export interface UpsertOptions {
-    /** Whether to create a version snapshot before updating (default: true) */
-    createVersionOnChange?: boolean;
-    /** Allow overwriting changes made via dashboard/API (default: false) */
-    allowOverwriteExternalChanges?: boolean;
-}
-export interface DispatchOptions {
-    streamResponse?: boolean;
-    modelOverride?: string;
-    recordMode?: 'existing' | 'create' | 'virtual';
-    flowMode?: 'existing' | 'create' | 'virtual' | 'upsert';
-    storeResults?: boolean;
-    autoAppendMetadata?: boolean;
-    debugMode?: boolean;
-    createVersion?: boolean;
-    versionType?: 'published' | 'draft' | 'test' | 'virtual';
-    versionLabel?: string;
-    versionNotes?: string;
-    flowVersionId?: string;
-    /** Options for upsert mode (only used when flowMode is 'upsert') */
-    upsertOptions?: UpsertOptions;
-}
-export interface Message {
-    role: 'system' | 'user' | 'assistant';
-    content: MessageContent;
-}
-export interface FlowPausedEvent {
-    type: 'flow_await';
-    executionId: string;
-    flowId: string;
-    toolId: string;
-    toolName: string;
-    awaitedAt: string;
-}
-export interface StepWaitingLocalEvent {
-    type: 'step_await';
-    id: string;
-    name: string;
-    index: number;
-    stepType: string;
-    toolId: string;
-    toolName: string;
-    executionId: string;
-    parameters: any;
-}
-/**
- * Emitted when a fallback chain starts execution
- */
-export interface FallbacksInitiatedEvent {
-    type: 'fallbacks_initiated';
-    id: string;
-    totalFallbacks: number;
-    originalError: string;
-    timestamp: string;
-}
-/**
- * Emitted when a fallback attempt starts
- */
-export interface FallbackStartEvent {
-    type: 'fallback_start';
-    id: string;
-    attempt: number;
-    fallbackType: string;
-    timestamp: string;
-}
-/**
- * Emitted when a fallback attempt succeeds
- */
-export interface FallbackSuccessEvent {
-    type: 'fallback_success';
-    id: string;
-    attempt: number;
-    fallbackType: string;
-    timestamp: string;
-}
-/**
- * Emitted when a fallback attempt fails
- */
-export interface FallbackFailEvent {
-    type: 'fallback_fail';
-    id: string;
-    attempt: number;
-    fallbackType: string;
-    error: string;
-    timestamp: string;
-}
-/**
- * Emitted when all fallbacks in the chain have been exhausted
- */
-export interface FallbacksExhaustedEvent {
-    type: 'fallbacks_exhausted';
-    id: string;
-    totalAttempts: number;
-    finalError: string;
-    timestamp: string;
-}
-export interface FlowStartEvent {
-    type: 'flow_start';
-    flowId: string;
-    flowName: string;
-    totalSteps: number;
-}
-export interface StepStartEvent {
-    type: 'step_start';
-    id: string;
-    name: string;
-    index: number;
-    stepType: string;
-}
-export interface StepDeltaEvent {
-    type: 'step_delta';
-    id: string;
-    chunk: string;
-    index: number;
-}
-/** @deprecated Use StepDeltaEvent instead */
-export type StepChunkEvent = StepDeltaEvent;
-export interface StepCompleteEvent {
-    type: 'step_complete';
-    id: string;
-    name: string;
-    index: number;
-    stepType: string;
-    /** Step result - used by all step types */
-    result?: any;
-    executionTime: number;
-}
-export interface FlowCompleteEvent {
-    type: 'flow_complete';
-    flowId: string;
-    totalSteps: number;
-    successfulSteps: number;
-    failedSteps: number;
-    executionTime: number;
-}
-export interface FlowErrorEvent {
-    type: 'flow_error';
-    error: string;
-    stepId?: string;
-}
-/**
- * Union type of all possible SSE events
- */
-export type StreamEvent = FlowStartEvent | StepStartEvent | StepDeltaEvent | StepCompleteEvent | FlowCompleteEvent | FlowErrorEvent | FlowPausedEvent | StepWaitingLocalEvent | FallbacksInitiatedEvent | FallbackStartEvent | FallbackSuccessEvent | FallbackFailEvent | FallbacksExhaustedEvent;
-/**
- * Callbacks for streaming flow execution
- *
- * @example
- * ```typescript
- * await flow.run(apiClient, options, {
- *   onStepStart: (event) => console.log('Starting:', event.name),
- *   onStepDelta: (chunk, event) => process.stdout.write(chunk),
- *   onStepComplete: (result, event) => console.log('Done:', event.name),
- *   onFlowComplete: (event) => console.log('Flow complete'),
- *   onError: (error) => console.error(error),
- * })
- * ```
- */
-export interface StreamCallbacks {
-    /** Called when flow execution starts */
-    onFlowStart?: (event: FlowStartEvent) => void;
-    /** Called when a step starts executing */
-    onStepStart?: (event: StepStartEvent) => void;
-    /** Called for each chunk of streaming output from a step */
-    onStepDelta?: (chunk: string, event: StepDeltaEvent) => void;
-    /**
-     * @deprecated Use onStepDelta instead
-     * Called for each chunk of streaming output from a step
-     */
-    onStepChunk?: (chunk: string, event: StepDeltaEvent) => void;
-    /** Called when a step completes */
-    onStepComplete?: (result: any, event: StepCompleteEvent) => void;
-    /** Called when the entire flow completes */
-    onFlowComplete?: (event: FlowCompleteEvent) => void;
-    /** Called when an error occurs */
-    onError?: (error: Error) => void;
-}
-/**
- * Summary returned after flow execution completes
- */
-export interface FlowSummary {
-    flowId: string;
-    flowName: string;
-    totalSteps: number;
-    successfulSteps: number;
-    failedSteps: number;
-    executionTime: number;
-    /** Results from each step, keyed by step name */
-    results: Map<string, any>;
-    /** Whether the flow completed successfully */
-    success: boolean;
-}
-export declare class FlowBuilder {
-    private flowConfig;
-    private steps;
-    private recordConfig;
-    private messagesConfig;
-    private inputsConfig;
-    private optionsConfig;
-    private stepCounter;
-    private existingFlowId;
-    /**
-     * Initialize the flow with a name and optional description.
-     * Use this for virtual/one-off flows or when specifying flowMode in run().
-     */
-    createFlow(config: FlowConfig): this;
-    /**
-     * Define a flow for upsert - creates if it doesn't exist, updates if steps changed.
-     * This is the recommended pattern for code-first flow management.
-     *
-     * @example
-     * ```typescript
-     * const result = await new FlowBuilder()
-     *   .upsertFlow({
-     *     name: 'My Flow',
-     *     createVersionOnChange: true
-     *   })
-     *   .prompt({ name: 'Analyze', model: 'gpt-4o', userPrompt: '...' })
-     *   .run(apiClient, { streamResponse: true })
-     * ```
-     */
-    upsertFlow(config: UpsertFlowConfig): this;
-    /**
-     * Use an existing flow by ID instead of defining steps inline
-     *
-     * @example
-     * ```typescript
-     * const result = await new FlowBuilder()
-     *   .useExistingFlow('flow_abc123')
-     *   .withRecord({ name: 'Test', type: 'data' })
-     *   .run(apiClient, { streamResponse: true })
-     * ```
-     */
-    useExistingFlow(flowId: string): this;
-    /**
-     * Set the record configuration
-     */
-    withRecord(config: RecordConfig): this;
-    /**
-     * Set conversation messages
-     */
-    withMessages(messages: Message[]): this;
-    /**
-     * Set top-level input variables accessible as {{varName}} in templates
-     *
-     * @example
-     * ```typescript
-     * const result = await new FlowBuilder()
-     *   .useExistingFlow('flow_abc123')
-     *   .withInputs({
-     *     customerName: 'John',
-     *     topic: 'billing'
-     *   })
-     *   .run(apiClient, { streamResponse: true })
-     * ```
-     */
-    withInputs(inputs: Record<string, unknown>): this;
-    /**
-     * Set dispatch options
-     */
-    withOptions(options: DispatchOptions): this;
-    /**
-     * Add a prompt step
-     */
-    prompt(config: PromptStepConfig): this;
-    /**
-     * Add a fetch URL step
-     */
-    fetchUrl(config: FetchUrlStepConfig): this;
-    /**
-     * Add a transform data step
-     */
-    transformData(config: TransformDataStepConfig): this;
-    /**
-     * Add a set variable step
-     */
-    setVariable(config: SetVariableStepConfig): this;
-    /**
-     * Add a conditional step
-     */
-    conditional(config: ConditionalStepConfig): this;
-    /**
-     * Add a search step
-     */
-    search(config: SearchStepConfig): this;
-    /**
-     * Add a send email step
-     */
-    sendEmail(config: SendEmailStepConfig): this;
-    /**
-     * Add a send stream step
-     */
-    sendStream(config: SendStreamStepConfig): this;
-    /**
-     * Add a retrieve record step
-     */
-    retrieveRecord(config: RetrieveRecordStepConfig): this;
-    /**
-     * Add an upsert record step
-     */
-    upsertRecord(config: UpsertRecordStepConfig): this;
-    /**
-     * Add a vector search step
-     */
-    vectorSearch(config: VectorSearchStepConfig): this;
-    /**
-     * Add a generate embedding step
-     */
-    generateEmbedding(config: GenerateEmbeddingStepConfig): this;
-    /**
-     * Add a wait until step
-     */
-    waitUntil(config: WaitUntilStepConfig): this;
-    /**
-     * Add a send event step
-     */
-    sendEvent(config: SendEventStepConfig): this;
-    /**
-     * Add a send text step
-     */
-    sendText(config: SendTextStepConfig): this;
-    /**
-     * Add a fetch GitHub step
-     */
-    fetchGitHub(config: FetchGitHubStepConfig): this;
-    /**
-     * Build the final dispatch request configuration
-     */
-    build(): DispatchRequest;
-    /**
-     * Build and execute the flow with the provided client
-     *
-     * Returns a FlowResult that can be used to:
-     * - Process with callbacks via `.stream(callbacks)`
-     * - Get a specific step result via `.getResult(stepName)`
-     * - Get all results via `.getAllResults()`
-     * - Access raw response via `.raw`
-     *
-     * @param client - Client with dispatch capability
-     * @param options - Optional execution options (merged with any .withOptions() settings)
-     * @returns FlowResult for processing the streaming response
-     *
-     * @example
-     * ```typescript
-     * // Simple execution with result extraction
-     * const result = await flow.run(apiClient, { streamResponse: true })
-     * const analysis = await result.getResult('Analyze Data')
-     *
-     * // With streaming callbacks
-     * const result = await flow.run(apiClient, options)
-     * await result.stream({
-     *   onStepDelta: (chunk) => process.stdout.write(chunk),
-     *   onFlowComplete: () => console.log('Done!'),
-     * })
-     * ```
-     */
-    run(client: DispatchClient, options?: DispatchOptions): Promise<FlowResult>;
-    /**
-     * Build and execute the flow with callbacks for streaming events
-     *
-     * @param client - Client with dispatch capability
-     * @param options - Execution options (merged with any .withOptions() settings)
-     * @param callbacks - Callbacks for streaming events
-     * @returns FlowSummary when execution completes
-     *
-     * @example
-     * ```typescript
-     * const summary = await flow.run(apiClient, options, {
-     *   onStepStart: (event) => console.log('Starting:', event.name),
-     *   onStepDelta: (chunk) => process.stdout.write(chunk),
-     *   onStepComplete: (result, event) => console.log('Done:', event.name),
-     *   onFlowComplete: (event) => console.log('Flow complete!'),
-     * })
-     * ```
-     */
-    run(client: DispatchClient, options: DispatchOptions, callbacks: StreamCallbacks): Promise<FlowSummary>;
-    private addStep;
-}
-/**
- * Interface for clients that can dispatch flows
- */
-export interface DispatchClient {
-    /**
-     * Run a flow with local tools (automatic pause/resume loop)
-     *
-     * @param config - The dispatch request configuration
-     * @param localTools - Map of tool names to async functions that execute the tool logic
-     * @param callbacks - Optional callbacks for streaming events
-     * @returns The final result of the flow execution or summary if streaming
-     */
-    runWithLocalTools(config: DispatchRequest, localTools: Record<string, (args: any) => Promise<any>>, callbacks?: StreamCallbacks): Promise<FlowResult | FlowSummary>;
-    dispatch(config: DispatchRequest): Promise<Response>;
-}
-/**
- * FlowBuilder that is bound to a client for direct execution
- *
- * @example
- * ```typescript
- * // Via RuntypeClient.flow()
- * const result = await runtype
- *   .flow('My Flow')
- *   .fetchUrl({ name: 'Fetch', url: '...', outputVariable: 'data' })
- *   .prompt({ name: 'Process', model: 'gpt-4', userPrompt: '...' })
- *   .run({ streamResponse: true })
- *
- * const data = await result.getResult('Process')
- * ```
- */
-export declare class ClientFlowBuilder extends FlowBuilder {
-    private boundClient;
-    constructor(client: DispatchClient, name: string);
-    /**
-     * Build and execute the flow using the bound client
-     *
-     * For ClientFlowBuilder, you can either:
-     * 1. Pass a client (which is ignored, the bound client is used)
-     * 2. Pass options directly as the first argument
-     *
-     * @example
-     * ```typescript
-     * // Simple execution (no args needed)
-     * const result = await builder.run()
-     * const data = await result.getResult('Process')
-     *
-     * // With options only
-     * const result = await builder.run({ streamResponse: true, flowMode: 'virtual' })
-     *
-     * // With options and callbacks
-     * const summary = await builder.run({ streamResponse: true }, {
-     *   onStepDelta: (chunk) => process.stdout.write(chunk),
-     *   onFlowComplete: () => console.log('Done!'),
-     * })
-     *
-     * // Parent class signature (client ignored)
-     * const result = await builder.run(someClient, { streamResponse: true })
-     * ```
-     */
-    run(): Promise<FlowResult>;
-    run(options: DispatchOptions): Promise<FlowResult>;
-    run(options: DispatchOptions, callbacks: StreamCallbacks): Promise<FlowSummary>;
-    run(localTools: Record<string, (args: any) => Promise<any>>): Promise<FlowResult>;
-    run(options: DispatchOptions, localTools: Record<string, (args: any) => Promise<any>>): Promise<FlowResult>;
-    run(localTools: Record<string, (args: any) => Promise<any>>, callbacks: StreamCallbacks): Promise<FlowSummary>;
-    run(options: DispatchOptions, localTools: Record<string, (args: any) => Promise<any>>, callbacks: StreamCallbacks): Promise<FlowSummary>;
-    run(client: DispatchClient, options?: DispatchOptions): Promise<FlowResult>;
-    run(client: DispatchClient, options: DispatchOptions, callbacks: StreamCallbacks): Promise<FlowSummary>;
-}
-/**
- * Create an external runtime tool definition.
- *
- * External tools make HTTP requests to external APIs with support for
- * variable substitution in URLs and headers.
- *
- * Special internal variables are available for auth:
- * - `{{_internal.auth_token}}` - Bearer token for Runtype API auth
- * - `{{_internal.user_id}}` - Current user ID
- * - `{{_internal.org_id}}` - Current organization ID
- *
- * @example
- * ```typescript
- * const listFlowsTool = createExternalTool({
- *   name: 'list_flows',
- *   description: 'List all flows in the workspace',
- *   parametersSchema: {
- *     type: 'object',
- *     properties: {
- *       limit: { type: 'number', description: 'Max results', default: 20 }
- *     }
- *   },
- *   url: 'https://api.runtype.com/v1/flows',
- *   method: 'GET',
- *   headers: { Authorization: '{{_internal.auth_token}}' }
- * })
- * ```
- */
-export declare function createExternalTool(config: {
-    name: string;
-    description: string;
-    parametersSchema: any;
-    url: string;
-    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
-    headers?: Record<string, string>;
-}): RuntimeTool;
-//# sourceMappingURL=flow-builder.d.ts.map