fix(firecrawl): correct map's declared shape, a crash path, and a timeout race

map declared links as an array of strings, but v2 returns MapDocument objects
{url, title?, description?} -- so every consumer reading <firecrawl.links> as
URLs got [object Object]. Same declared-vs-real class this branch fixed for
search, one file over.

scrape's transformResponse read data.data.markdown unguarded. Firecrawl's error
bodies carry no data key, so any non-happy path threw a TypeError instead of
surfacing the error; every sibling tool already guards.

The country description claimed an unconditional "US" default. The schema
applies it only when location is unset.

sources and categories were unconstrained strings against a strict-object
schema, so an LLM emitting an invalid value got a hard 400. Constrained with
const unions, verified to survive into the model-visible schema. Adds the
'developer' category, which is a live enum member with its own aliases.

timeout shadowed the transport's reserved param on the three external tools.
The units agree, so this looked safe -- but the 30s headroom the executor adds
applies only to internal routes, and the external branch passes the deadline
bare. Sim's clock starts earlier, so Sim always won the race and the user never
saw Firecrawl's structured 408. parse is internal-route and keeps the old name.

The subBlock's condition only hid the field, so a stale value still reached the
transport on operations that never declared it; the mapper now clears it once.

Author: waleedlatif1

apps/sim/blocks/blocks/firecrawl.ts

@@ -527,7 +527,20 @@ Example 2 - Product Data:
           jobId,
         } = params
 
-        const result: Record<string, any> = { apiKey }
+        /**
+         * `timeout` is reserved by the tool request transport as the outbound fetch
+         * deadline. On the external branch it is passed through bare, arming Sim's
+         * abort at the exact budget Firecrawl was given, on a clock that starts
+         * earlier — so Sim always wins and the caller loses Firecrawl's structured
+         * 408. Clear it for every operation; the external tools carry the value as
+         * `firecrawlTimeout` instead, while `parse` posts to an internal route that
+         * wants the deadline propagated and sets it back below.
+         *
+         * Clearing it here rather than per-case also covers the operations whose
+         * `timeout` subBlock is hidden by `condition`: the saved value survives an
+         * operation switch and would otherwise still reach the transport.
+         */
+        const result: Record<string, any> = { apiKey, timeout: undefined }
 
         switch (operation) {
           case 'scrape':
@@ -544,15 +557,15 @@ Example 2 - Product Data:
                 }
               }
             }
-            if (timeout) result.timeout = Number.parseInt(timeout)
+            if (timeout) result.firecrawlTimeout = Number.parseInt(timeout)
             if (waitFor) result.waitFor = Number.parseInt(waitFor)
             if (onlyMainContent != null) result.onlyMainContent = onlyMainContent
             if (mobile != null) result.mobile = mobile
             break
 
           case 'search':
             if (query) result.query = query
-            if (timeout) result.timeout = Number.parseInt(timeout)
+            if (timeout) result.firecrawlTimeout = Number.parseInt(timeout)
             if (limit) result.limit = Number.parseInt(limit)
             if (params.ignoreInvalidURLs != null) {
               result.ignoreInvalidURLs = params.ignoreInvalidURLs
@@ -795,7 +808,11 @@ Example 2 - Product Data:
     invalidURLs: { type: 'json', description: 'URLs skipped because they were invalid' },
     // Map output
     success: { type: 'boolean', description: 'Operation success status' },
-    links: { type: 'json', description: 'Discovered URLs array' },
+    links: {
+      type: 'json',
+      description:
+        'Discovered links, each an object with `url` and optional `title`/`description`. Reference `<firecrawl.links>[i].url` for the address — the entry itself is no longer a bare URL string.',
+    },
     // Extract output
     sources: { type: 'json', description: 'Data sources array' },
     tokensUsed: { type: 'number', description: 'Tokens consumed by the extract job' },

apps/sim/tools/firecrawl/map.test.ts

@@ -0,0 +1,67 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import { mapTool } from '@/tools/firecrawl/map'
+import type { MapParams } from '@/tools/firecrawl/types'
+
+const jsonOk = (body: unknown) =>
+  new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' },
+  })
+
+const mapParams: MapParams = { apiKey: 'test-key', url: 'https://example.com' }
+
+const resolveBody = (params: MapParams): Record<string, unknown> =>
+  mapTool.request.body!(params) as Record<string, unknown>
+
+describe('firecrawl map declared links shape', () => {
+  it('declares links as MapDocument objects, not bare URL strings', () => {
+    const links = mapTool.outputs.links as {
+      type: string
+      items?: { type?: string; properties?: Record<string, unknown> }
+    }
+
+    expect(links.type).toBe('array')
+    expect(links.items?.type).toBe('object')
+    expect(Object.keys(links.items?.properties ?? {}).sort()).toEqual([
+      'description',
+      'title',
+      'url',
+    ])
+  })
+
+  it('passes the object-shaped links Firecrawl v2 actually returns straight through', async () => {
+    const response = await mapTool.transformResponse!(
+      jsonOk({
+        success: true,
+        id: 'map-1',
+        links: [
+          { url: 'https://example.com/a', title: 'A', description: 'first' },
+          { url: 'https://example.com/b' },
+        ],
+      }),
+      mapParams
+    )
+
+    expect(response.output.links).toEqual([
+      { url: 'https://example.com/a', title: 'A', description: 'first' },
+      { url: 'https://example.com/b' },
+    ])
+    expect(response.output.links[0].url).toBe('https://example.com/a')
+  })
+})
+
+describe('firecrawl map timeout is not the transport deadline', () => {
+  it('does not declare the transport-reserved `timeout` param', () => {
+    expect(mapTool.params.timeout).toBeUndefined()
+    expect(mapTool.params.firecrawlTimeout).toBeDefined()
+  })
+
+  it('maps firecrawlTimeout onto the request body as Firecrawl `timeout`', () => {
+    const body = resolveBody({ ...mapParams, firecrawlTimeout: 45000 })
+
+    expect(body.timeout).toBe(45000)
+  })
+})

apps/sim/tools/firecrawl/map.ts

@@ -1,5 +1,6 @@
 import { firecrawlHosting } from '@/tools/firecrawl/hosting'
 import type { MapParams, MapResponse } from '@/tools/firecrawl/types'
+import { MAP_DOCUMENT_OUTPUT_PROPERTIES } from '@/tools/firecrawl/types'
 import type { ToolConfig } from '@/tools/types'
 
 export const mapTool: ToolConfig<MapParams, MapResponse> = {
@@ -47,11 +48,12 @@ export const mapTool: ToolConfig<MapParams, MapResponse> = {
       description:
         'Maximum number of links to return (e.g., 100, 1000, 5000). Max: 100,000, default: 5,000',
     },
-    timeout: {
+    firecrawlTimeout: {
       type: 'number',
       required: false,
       visibility: 'user-only',
-      description: 'Request timeout in milliseconds',
+      description:
+        "How long Firecrawl may spend on the map, in milliseconds. Sent as `timeout` in the request body; it does not bound Sim's own transport deadline.",
     },
     location: {
       type: 'json',
@@ -88,7 +90,7 @@ export const mapTool: ToolConfig<MapParams, MapResponse> = {
       if (typeof params.ignoreQueryParameters === 'boolean')
         body.ignoreQueryParameters = params.ignoreQueryParameters
       if (params.limit) body.limit = Number(params.limit)
-      if (params.timeout) body.timeout = Number(params.timeout)
+      if (params.firecrawlTimeout) body.timeout = Number(params.firecrawlTimeout)
       if (params.location) body.location = params.location
 
       return body
@@ -115,9 +117,11 @@ export const mapTool: ToolConfig<MapParams, MapResponse> = {
     },
     links: {
       type: 'array',
-      description: 'Array of discovered URLs from the website',
+      description:
+        'Discovered links. Each entry is an object with `url` and optional `title`/`description` — read `<firecrawl.links>[i].url` for the address, not the entry itself.',
       items: {
-        type: 'string',
+        type: 'object',
+        properties: MAP_DOCUMENT_OUTPUT_PROPERTIES,
       },
     },
   },

apps/sim/tools/firecrawl/scrape.test.ts

@@ -0,0 +1,65 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import { scrapeTool } from '@/tools/firecrawl/scrape'
+import type { ScrapeParams } from '@/tools/firecrawl/types'
+
+const json = (body: unknown, status: number) =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  })
+
+const scrapeParams: ScrapeParams = { apiKey: 'test-key', url: 'https://example.com' }
+
+const resolveBody = (params: ScrapeParams): Record<string, unknown> =>
+  scrapeTool.request.body!(params) as Record<string, unknown>
+
+describe('firecrawl scrape error handling', () => {
+  it('does not throw on a Firecrawl error body that carries no `data` key', async () => {
+    const response = await scrapeTool.transformResponse!(
+      json({ success: false, error: 'Request timed out' }, 408),
+      scrapeParams
+    )
+
+    expect(response.output.markdown).toBeUndefined()
+    expect(response.output.metadata).toBeUndefined()
+  })
+
+  it('still projects the document on a successful response', async () => {
+    const response = await scrapeTool.transformResponse!(
+      json(
+        {
+          success: true,
+          data: {
+            markdown: '# Hi',
+            html: '<h1>Hi</h1>',
+            metadata: { title: 'Hi', sourceURL: 'https://example.com', statusCode: 200 },
+          },
+          creditsUsed: 1,
+        },
+        200
+      ),
+      scrapeParams
+    )
+
+    expect(response.output.markdown).toBe('# Hi')
+    expect(response.output.html).toBe('<h1>Hi</h1>')
+    expect(response.output.metadata.title).toBe('Hi')
+    expect(response.output.creditsUsed).toBe(1)
+  })
+})
+
+describe('firecrawl scrape timeout is not the transport deadline', () => {
+  it('does not declare the transport-reserved `timeout` param', () => {
+    expect(scrapeTool.params.timeout).toBeUndefined()
+    expect(scrapeTool.params.firecrawlTimeout).toBeDefined()
+  })
+
+  it('maps firecrawlTimeout onto the request body as Firecrawl `timeout`', () => {
+    const body = resolveBody({ ...scrapeParams, firecrawlTimeout: 45000 })
+
+    expect(body.timeout).toBe(45000)
+  })
+})

apps/sim/tools/firecrawl/scrape.ts

@@ -36,6 +36,13 @@ export const scrapeTool: ToolConfig<ScrapeParams, ScrapeResponse> = {
       visibility: 'hidden',
       description: 'Options for content scraping',
     },
+    firecrawlTimeout: {
+      type: 'number',
+      required: false,
+      visibility: 'user-only',
+      description:
+        "How long Firecrawl may spend on the scrape, in milliseconds. Sent as `timeout` in the request body; it does not bound Sim's own transport deadline.",
+    },
     apiKey: {
       type: 'string',
       required: true,
@@ -91,7 +98,7 @@ export const scrapeTool: ToolConfig<ScrapeParams, ScrapeResponse> = {
       if (typeof params.mobile === 'boolean') body.mobile = params.mobile
       if (typeof params.skipTlsVerification === 'boolean')
         body.skipTlsVerification = params.skipTlsVerification
-      if (params.timeout) body.timeout = Number(params.timeout)
+      if (params.firecrawlTimeout) body.timeout = Number(params.firecrawlTimeout)
       if (params.parsers) body.parsers = params.parsers
       if (params.actions) body.actions = params.actions
       if (params.location) body.location = params.location
@@ -113,13 +120,14 @@ export const scrapeTool: ToolConfig<ScrapeParams, ScrapeResponse> = {
 
   transformResponse: async (response: Response) => {
     const data = await response.json()
+    const document = data.data ?? {}
 
     return {
       success: true,
       output: {
-        markdown: data.data.markdown,
-        html: data.data.html,
-        metadata: data.data.metadata,
+        markdown: document.markdown,
+        html: document.html,
+        metadata: document.metadata,
         creditsUsed: data.creditsUsed,
       },
     }