feat(starterinput): added option to specify input format for starter block for api triggered executions (#204)

* added docs to landing page

* added basic input format for starter block

* improvements for input format for api calls, tested with and without input format

* restore old db configs for idle timeout and connect timeout

* added tests for execution with formatted input

* added syncing of subblock values to make input format persist

* fixed empty variable name bug

* hide api key in deployment notif, fix db issues

Author: waleedlatif1

sim/app/(landing)/components/nav-client.tsx

@@ -49,6 +49,13 @@ export default function NavClient({ children }: { children: React.ReactNode }) {
 
         {/* Social media icons */}
         <div className={`flex items-center ${isMobile ? 'gap-2' : 'gap-3'}`}>
+          <a
+            href={`${process.env.NEXT_PUBLIC_DOCS_URL}/docs`}
+            className="text-white/80 hover:text-white/100 text-xl p-2 rounded-md hover:scale-[1.04] transition-colors transition-transform duration-200"
+            rel="noopener noreferrer"
+          >
+            docs
+          </a>
           <a
             href="https://x.com/simstudioai"
             className="text-white/80 hover:text-white/100 p-2 rounded-md group hover:scale-[1.04] transition-colors transition-transform duration-200"

sim/app/api/workflows/[id]/execute/route.test.ts

@@ -3,10 +3,24 @@
  *
  * @vitest-environment node
  */
+import { NextRequest } from 'next/server'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { createMockRequest } from '@/app/api/__test-utils__/utils'
 
 describe('Workflow Execution API Route', () => {
+  let executeMock = vi.fn().mockResolvedValue({
+    success: true,
+    output: {
+      response: 'Test response',
+    },
+    logs: [],
+    metadata: {
+      duration: 123,
+      startTime: new Date().toISOString(),
+      endTime: new Date().toISOString(),
+    },
+  })
+
   beforeEach(() => {
     vi.resetModules()
 
@@ -48,21 +62,24 @@ describe('Workflow Execution API Route', () => {
       }),
     }))
 
+    // Reset execute mock to track calls
+    executeMock = vi.fn().mockResolvedValue({
+      success: true,
+      output: {
+        response: 'Test response',
+      },
+      logs: [],
+      metadata: {
+        duration: 123,
+        startTime: new Date().toISOString(),
+        endTime: new Date().toISOString(),
+      },
+    })
+
     // Mock executor
     vi.doMock('@/executor', () => ({
       Executor: vi.fn().mockImplementation(() => ({
-        execute: vi.fn().mockResolvedValue({
-          success: true,
-          output: {
-            response: 'Test response',
-          },
-          logs: [],
-          metadata: {
-            duration: 123,
-            startTime: new Date().toISOString(),
-            endTime: new Date().toISOString(),
-          },
-        }),
+        execute: executeMock,
       })),
     }))
 
@@ -110,6 +127,11 @@ describe('Workflow Execution API Route', () => {
             })),
           })),
         })),
+        update: vi.fn().mockImplementation(() => ({
+          set: vi.fn().mockImplementation(() => ({
+            where: vi.fn().mockResolvedValue(undefined),
+          })),
+        })),
       }
 
       return { db: mockDb }
@@ -178,6 +200,9 @@ describe('Workflow Execution API Route', () => {
     // Verify executor was initialized
     const Executor = (await import('@/executor')).Executor
     expect(Executor).toHaveBeenCalled()
+
+    // Verify execute was called with undefined input (GET requests don't have body)
+    expect(executeMock).toHaveBeenCalledWith('workflow-id')
   })
 
   /**
@@ -232,6 +257,124 @@ describe('Workflow Execution API Route', () => {
     // Verify executor was constructed
     const Executor = (await import('@/executor')).Executor
     expect(Executor).toHaveBeenCalled()
+
+    // Verify execute was called with the input body
+    expect(executeMock).toHaveBeenCalledWith('workflow-id')
+    // Verify the body was passed to the executor constructor
+    expect(Executor).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.anything(),
+      expect.anything(),
+      requestBody
+    )
+  })
+
+  /**
+   * Test POST execution with structured input matching the input format
+   */
+  it('should execute workflow with structured input matching the input format', async () => {
+    // Create structured input matching the expected input format
+    const structuredInput = {
+      firstName: 'John',
+      age: 30,
+      isActive: true,
+      preferences: { theme: 'dark' },
+      tags: ['test', 'api'],
+    }
+
+    // Create a mock request with the structured input
+    const req = createMockRequest('POST', structuredInput)
+
+    // Create params similar to what Next.js would provide
+    const params = Promise.resolve({ id: 'workflow-id' })
+
+    // Import the handler after mocks are set up
+    const { POST } = await import('./route')
+
+    // Call the handler
+    const response = await POST(req, { params })
+
+    // Ensure response exists and is successful
+    expect(response).toBeDefined()
+    expect(response.status).toBe(200)
+
+    // Parse the response body
+    const data = await response.json()
+    expect(data).toHaveProperty('success', true)
+
+    // Verify the executor was constructed with the structured input
+    const Executor = (await import('@/executor')).Executor
+    expect(Executor).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.anything(),
+      expect.anything(),
+      structuredInput
+    )
+  })
+
+  /**
+   * Test POST execution with empty request body
+   */
+  it('should execute workflow with empty request body', async () => {
+    // Create a mock request with empty body
+    const req = createMockRequest('POST')
+
+    // Create params similar to what Next.js would provide
+    const params = Promise.resolve({ id: 'workflow-id' })
+
+    // Import the handler after mocks are set up
+    const { POST } = await import('./route')
+
+    // Call the handler
+    const response = await POST(req, { params })
+
+    // Ensure response exists and is successful
+    expect(response).toBeDefined()
+    expect(response.status).toBe(200)
+
+    // Parse the response body
+    const data = await response.json()
+    expect(data).toHaveProperty('success', true)
+
+    // Verify the executor was constructed with an empty object
+    const Executor = (await import('@/executor')).Executor
+    expect(Executor).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.anything(),
+      expect.anything(),
+      {}
+    )
+  })
+
+  /**
+   * Test POST execution with invalid JSON body
+   */
+  it('should handle invalid JSON in request body', async () => {
+    // Create a mock request with invalid JSON text
+    const req = new NextRequest('https://example.com/api/workflows/workflow-id/execute', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: 'this is not valid JSON',
+    })
+
+    // Create params similar to what Next.js would provide
+    const params = Promise.resolve({ id: 'workflow-id' })
+
+    // Import the handler after mocks are set up
+    const { POST } = await import('./route')
+
+    // Call the handler - should throw an error when trying to parse the body
+    const response = await POST(req, { params })
+
+    // Expect error response due to JSON parsing failure
+    expect(response.status).toBe(500)
+
+    const data = await response.json()
+    expect(data).toHaveProperty('error')
+    // Check for JSON parse error message rather than "Failed to execute workflow"
+    expect(data.error).toContain('JSON')
   })
 
   /**

sim/app/api/workflows/[id]/execute/route.ts

@@ -234,7 +234,9 @@ export async function POST(request: NextRequest, { params }: { params: Promise<{
       return createErrorResponse(validation.error.message, validation.error.status)
     }
 
-    const body = await request.json().catch(() => ({}))
+    const bodyText = await request.text()
+    const body = bodyText ? JSON.parse(bodyText) : {}
+
     const result = await executeWorkflow(validation.workflow, requestId, body)
     return createSuccessResponse(result)
   } catch (error: any) {

sim/app/w/[id]/components/control-bar/control-bar.tsx

@@ -43,6 +43,7 @@ import { useExecutionStore } from '@/stores/execution/store'
 import { useNotificationStore } from '@/stores/notifications/store'
 import { useGeneralStore } from '@/stores/settings/general/store'
 import { useWorkflowRegistry } from '@/stores/workflows/registry/store'
+import { useSubBlockStore } from '@/stores/workflows/subblock/store'
 import { useWorkflowStore } from '@/stores/workflows/workflow/store'
 import { useWorkflowExecution } from '../../hooks/use-workflow-execution'
 import { HistoryDropdownItem } from './components/history-dropdown-item/history-dropdown-item'
@@ -205,12 +206,64 @@ export function ControlBar() {
     removeWorkflow(activeWorkflowId)
   }
 
+  /**
+   * Get an example of the input format for the workflow
+   */
+  const getInputFormatExample = () => {
+    let inputFormatExample = ''
+    try {
+      // Find the starter block in the workflow
+      const blocks = Object.values(useWorkflowStore.getState().blocks)
+      const starterBlock = blocks.find((block) => block.type === 'starter')
+
+      if (starterBlock) {
+        const inputFormat = useSubBlockStore.getState().getValue(starterBlock.id, 'inputFormat')
+
+        // If input format is defined, create an example
+        if (inputFormat && Array.isArray(inputFormat) && inputFormat.length > 0) {
+          const exampleData: Record<string, any> = {}
+
+          // Create example values for each field
+          inputFormat.forEach((field) => {
+            if (field.name) {
+              switch (field.type) {
+                case 'string':
+                  exampleData[field.name] = 'example'
+                  break
+                case 'number':
+                  exampleData[field.name] = 42
+                  break
+                case 'boolean':
+                  exampleData[field.name] = true
+                  break
+                case 'object':
+                  exampleData[field.name] = { key: 'value' }
+                  break
+                case 'array':
+                  exampleData[field.name] = [1, 2, 3]
+                  break
+              }
+            }
+          })
+
+          inputFormatExample = ` -d '${JSON.stringify(exampleData)}'`
+        }
+      }
+    } catch (error) {
+      console.error('Error generating input format example:', error)
+    }
+
+    return inputFormatExample
+  }
+
   /**
    * Workflow deployment handler
    */
   const handleDeploy = async () => {
     if (!activeWorkflowId) return
 
+    const inputFormatExample = getInputFormatExample()
+
     // If already deployed, show the API info
     if (isDeployed) {
       // Try to find an existing API notification
@@ -249,7 +302,7 @@ export function ControlBar() {
             {
               label: 'Example curl command',
               content: apiKey
-                ? `curl -X POST -H "X-API-Key: ${apiKey}" -H "Content-Type: application/json" ${endpoint}`
+                ? `curl -X POST -H "X-API-Key: ${apiKey}" -H "Content-Type: application/json"${inputFormatExample} ${endpoint}`
                 : `You need an API key to call this endpoint. Visit your account settings to create one.`,
             },
           ],
@@ -292,7 +345,7 @@ export function ControlBar() {
           {
             label: 'Example curl command',
             content: apiKey
-              ? `curl -X POST -H "X-API-Key: ${apiKey}" -H "Content-Type: application/json" ${endpoint}`
+              ? `curl -X POST -H "X-API-Key: ${apiKey}" -H "Content-Type: application/json"${inputFormatExample} ${endpoint}`
               : `You need an API key to call this endpoint. Visit your account settings to create one.`,
           },
         ],