@open-mercato/web-research-firecrawl 0.7.1-develop.7194.1.ab4fc81f82

package/.turbo/turbo-build.log

@@ -0,0 +1,2 @@
+[build:web-research-firecrawl] found 2 entry points
+[build:web-research-firecrawl] built successfully

package/build.mjs

@@ -0,0 +1,10 @@
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { buildPackage } from '../../scripts/build-package.mjs'
+
+const packageDir = dirname(fileURLToPath(import.meta.url))
+
+await buildPackage(packageDir, {
+  name: 'web-research-firecrawl',
+  entryPoints: 'src/**/*.ts',
+})

package/dist/adapter.js

@@ -0,0 +1,160 @@
+import {
+  CONTRACT_VERSION,
+  READY,
+  defineAdapterModule,
+  notReady,
+  searchOk,
+  stripTrailingSlashes,
+  toOutcomeFailure
+} from "@open-mercato/web-research";
+import { z } from "zod";
+const firecrawlOptionsSchema = z.object({
+  apiKey: z.string().min(1).optional(),
+  baseUrl: z.url().optional(),
+  /** Ask Firecrawl to return page content inline, sparing a second round trip. */
+  includeContent: z.boolean().optional(),
+  timeoutMs: z.number().int().min(1e3).max(12e4).optional()
+});
+const DEFAULT_BASE_URL = "https://api.firecrawl.dev";
+const DEFAULT_TIMEOUT_MS = 2e4;
+const searchResponseSchema = z.object({
+  success: z.boolean().optional(),
+  data: z.array(
+    z.object({
+      url: z.string(),
+      title: z.string().nullish(),
+      description: z.string().nullish(),
+      markdown: z.string().nullish(),
+      publishedDate: z.string().nullish()
+    })
+  ).nullish()
+});
+const scrapeResponseSchema = z.object({
+  success: z.boolean().optional(),
+  data: z.object({
+    markdown: z.string().nullish(),
+    html: z.string().nullish(),
+    metadata: z.object({
+      title: z.string().nullish(),
+      sourceURL: z.string().nullish(),
+      statusCode: z.number().nullish()
+    }).nullish()
+  }).nullish()
+});
+function parseJson(body) {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return null;
+  }
+}
+function createFirecrawlAdapter(options) {
+  const apiKey = options.apiKey?.trim() ?? "";
+  const baseUrl = stripTrailingSlashes(options.baseUrl ?? DEFAULT_BASE_URL);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const includeContent = options.includeContent ?? true;
+  const post = (path, payload, context) => context.http.request(`${baseUrl}${path}`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${apiKey}`, "content-type": "application/json" },
+    body: JSON.stringify(payload),
+    accept: ["application/json"],
+    timeoutMs,
+    signal: context.signal
+  });
+  return {
+    id: "firecrawl",
+    kind: "api",
+    capabilities: {
+      search: true,
+      fetch: true,
+      snippets: true,
+      content: includeContent,
+      freshness: false,
+      siteFilter: true,
+      cost: "metered"
+    },
+    /** `billable` — issues a real /v1/search query. */
+    probeCost: "billable",
+    readiness: () => apiKey.length > 0 ? READY : notReady("Firecrawl API key is not set"),
+    async search(request, context) {
+      if (apiKey.length === 0) return { status: "unavailable", reason: "Firecrawl API key is not set" };
+      try {
+        const query = request.site ? `${request.query} site:${request.site}` : request.query;
+        const response = await post(
+          "/v1/search",
+          {
+            query,
+            limit: request.limit,
+            ...includeContent ? { scrapeOptions: { formats: ["markdown"] } } : {}
+          },
+          context
+        );
+        const parsed = searchResponseSchema.safeParse(parseJson(response.body));
+        if (!parsed.success) {
+          return { status: "error", reason: "Firecrawl returned an unrecognized response shape", retriable: false };
+        }
+        const results = (parsed.data.data ?? []).map((item) => ({
+          url: item.url,
+          title: item.title ?? null,
+          snippet: item.description ?? null,
+          content: item.markdown ?? null,
+          publishedAt: item.publishedDate ?? null
+        }));
+        context.report("ok", `Firecrawl returned ${results.length} result(s)`, { resultCount: results.length });
+        return searchOk(results);
+      } catch (error) {
+        return toOutcomeFailure(error);
+      }
+    },
+    async fetch(request, context) {
+      if (apiKey.length === 0) return { status: "unavailable", reason: "Firecrawl API key is not set" };
+      try {
+        const response = await post("/v1/scrape", { url: request.url, formats: ["markdown"] }, context);
+        const parsed = scrapeResponseSchema.safeParse(parseJson(response.body));
+        const data = parsed.success ? parsed.data.data : null;
+        const text = data?.markdown?.trim() ?? "";
+        if (text.length === 0) {
+          return { status: "error", reason: "Firecrawl returned no readable content", retriable: false };
+        }
+        return {
+          status: "ok",
+          page: {
+            url: data?.metadata?.sourceURL ?? request.url,
+            title: data?.metadata?.title ?? null,
+            text,
+            contentType: "text/markdown",
+            status: data?.metadata?.statusCode ?? 200,
+            truncated: false,
+            // Firecrawl renders server-side, so content that needed JavaScript
+            // arrives without us running a browser at all.
+            renderedWith: "browser"
+          }
+        };
+      } catch (error) {
+        return toOutcomeFailure(error);
+      }
+    },
+    async healthCheck(context) {
+      if (apiKey.length === 0) return { ok: false, detail: "Firecrawl API key is not set" };
+      try {
+        await post("/v1/search", { query: "open mercato health check", limit: 1 }, context);
+        return { ok: true };
+      } catch (error) {
+        return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+      }
+    }
+  };
+}
+const firecrawlAdapterModule = defineAdapterModule({
+  id: "firecrawl",
+  kind: "api",
+  contractVersion: CONTRACT_VERSION,
+  optionsSchema: firecrawlOptionsSchema,
+  createAdapter: createFirecrawlAdapter
+});
+export {
+  createFirecrawlAdapter,
+  firecrawlAdapterModule,
+  firecrawlOptionsSchema
+};
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/adapter.ts"],
+  "sourcesContent": ["import {\n  CONTRACT_VERSION,\n  READY,\n  defineAdapterModule,\n  notReady,\n  searchOk,\n  stripTrailingSlashes,\n  toOutcomeFailure,\n  type AdapterContext,\n  type FetchOutcome,\n  type FetchRequest,\n  type RawResult,\n  type SearchAdapter,\n  type SearchOutcome,\n} from '@open-mercato/web-research'\nimport { z } from 'zod'\n\nexport const firecrawlOptionsSchema = z.object({\n  apiKey: z.string().min(1).optional(),\n  baseUrl: z.url().optional(),\n  /** Ask Firecrawl to return page content inline, sparing a second round trip. */\n  includeContent: z.boolean().optional(),\n  timeoutMs: z.number().int().min(1000).max(120_000).optional(),\n})\n\nexport type FirecrawlOptions = z.infer<typeof firecrawlOptionsSchema>\n\nconst DEFAULT_BASE_URL = 'https://api.firecrawl.dev'\nconst DEFAULT_TIMEOUT_MS = 20_000\n\nconst searchResponseSchema = z.object({\n  success: z.boolean().optional(),\n  data: z\n    .array(\n      z.object({\n        url: z.string(),\n        title: z.string().nullish(),\n        description: z.string().nullish(),\n        markdown: z.string().nullish(),\n        publishedDate: z.string().nullish(),\n      }),\n    )\n    .nullish(),\n})\n\nconst scrapeResponseSchema = z.object({\n  success: z.boolean().optional(),\n  data: z\n    .object({\n      markdown: z.string().nullish(),\n      html: z.string().nullish(),\n      metadata: z\n        .object({\n          title: z.string().nullish(),\n          sourceURL: z.string().nullish(),\n          statusCode: z.number().nullish(),\n        })\n        .nullish(),\n    })\n    .nullish(),\n})\n\nfunction parseJson(body: string): unknown {\n  try {\n    return JSON.parse(body)\n  } catch {\n    return null\n  }\n}\n\nexport function createFirecrawlAdapter(options: FirecrawlOptions): SearchAdapter {\n  const apiKey = options.apiKey?.trim() ?? ''\n  const baseUrl = stripTrailingSlashes(options.baseUrl ?? DEFAULT_BASE_URL)\n  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS\n  const includeContent = options.includeContent ?? true\n\n  const post = (path: string, payload: unknown, context: AdapterContext) =>\n    context.http.request(`${baseUrl}${path}`, {\n      method: 'POST',\n      headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },\n      body: JSON.stringify(payload),\n      accept: ['application/json'],\n      timeoutMs,\n      signal: context.signal,\n    })\n\n  return {\n    id: 'firecrawl',\n    kind: 'api',\n    capabilities: {\n      search: true,\n      fetch: true,\n      snippets: true,\n      content: includeContent,\n      freshness: false,\n      siteFilter: true,\n      cost: 'metered',\n    },\n    /** `billable` \u2014 issues a real /v1/search query. */\n    probeCost: 'billable' as const,\n    readiness: () => (apiKey.length > 0 ? READY : notReady('Firecrawl API key is not set')),\n\n    async search(request, context): Promise<SearchOutcome> {\n      if (apiKey.length === 0) return { status: 'unavailable', reason: 'Firecrawl API key is not set' }\n      try {\n        const query = request.site ? `${request.query} site:${request.site}` : request.query\n        const response = await post(\n          '/v1/search',\n          {\n            query,\n            limit: request.limit,\n            ...(includeContent ? { scrapeOptions: { formats: ['markdown'] } } : {}),\n          },\n          context,\n        )\n        const parsed = searchResponseSchema.safeParse(parseJson(response.body))\n        if (!parsed.success) {\n          return { status: 'error', reason: 'Firecrawl returned an unrecognized response shape', retriable: false }\n        }\n        const results: RawResult[] = (parsed.data.data ?? []).map((item) => ({\n          url: item.url,\n          title: item.title ?? null,\n          snippet: item.description ?? null,\n          content: item.markdown ?? null,\n          publishedAt: item.publishedDate ?? null,\n        }))\n        context.report('ok', `Firecrawl returned ${results.length} result(s)`, { resultCount: results.length })\n        return searchOk(results)\n      } catch (error) {\n        return toOutcomeFailure(error)\n      }\n    },\n\n    async fetch(request: FetchRequest, context): Promise<FetchOutcome> {\n      if (apiKey.length === 0) return { status: 'unavailable', reason: 'Firecrawl API key is not set' }\n      try {\n        const response = await post('/v1/scrape', { url: request.url, formats: ['markdown'] }, context)\n        const parsed = scrapeResponseSchema.safeParse(parseJson(response.body))\n        const data = parsed.success ? parsed.data.data : null\n        const text = data?.markdown?.trim() ?? ''\n        if (text.length === 0) {\n          return { status: 'error', reason: 'Firecrawl returned no readable content', retriable: false }\n        }\n        return {\n          status: 'ok',\n          page: {\n            url: data?.metadata?.sourceURL ?? request.url,\n            title: data?.metadata?.title ?? null,\n            text,\n            contentType: 'text/markdown',\n            status: data?.metadata?.statusCode ?? 200,\n            truncated: false,\n            // Firecrawl renders server-side, so content that needed JavaScript\n            // arrives without us running a browser at all.\n            renderedWith: 'browser',\n          },\n        }\n      } catch (error) {\n        return toOutcomeFailure(error)\n      }\n    },\n\n    async healthCheck(context) {\n      if (apiKey.length === 0) return { ok: false, detail: 'Firecrawl API key is not set' }\n      try {\n        await post('/v1/search', { query: 'open mercato health check', limit: 1 }, context)\n        return { ok: true }\n      } catch (error) {\n        return { ok: false, detail: error instanceof Error ? error.message : String(error) }\n      }\n    },\n  }\n}\n\nexport const firecrawlAdapterModule = defineAdapterModule({\n  id: 'firecrawl',\n  kind: 'api',\n  contractVersion: CONTRACT_VERSION,\n  optionsSchema: firecrawlOptionsSchema,\n  createAdapter: createFirecrawlAdapter,\n})\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/index.js

@@ -0,0 +1,13 @@
+import {
+  createFirecrawlAdapter,
+  firecrawlAdapterModule,
+  firecrawlOptionsSchema
+} from "./adapter.js";
+import { firecrawlAdapterModule as firecrawlAdapterModule2 } from "./adapter.js";
+export {
+  createFirecrawlAdapter,
+  firecrawlAdapterModule2 as default,
+  firecrawlAdapterModule,
+  firecrawlOptionsSchema
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": ["export {\n  createFirecrawlAdapter,\n  firecrawlAdapterModule,\n  firecrawlOptionsSchema,\n  type FirecrawlOptions,\n} from './adapter'\n\nexport { firecrawlAdapterModule as default } from './adapter'\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAEK;AAEP,SAAmC,0BAA1BA,+BAAyC;",
+  "names": ["firecrawlAdapterModule"]
+}

package/jest.config.cjs

@@ -0,0 +1,28 @@
+/** @type {import('jest').Config} */
+const base = require('../../jest.config.base.cjs')
+
+module.exports = {
+  ...base,
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  watchman: false,
+  rootDir: '.',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],
+  moduleNameMapper: {
+    '^@open-mercato/web-research/(.*)$': '<rootDir>/../web-research/src/$1',
+    '^@open-mercato/web-research$': '<rootDir>/../web-research/src/index.ts',
+  },
+  transform: {
+    '^.+\\.(t|j)sx?$': [
+      'ts-jest',
+      {
+        tsconfig: {
+          rootDir: '.',
+          ignoreDeprecations: '6.0',
+        },
+      },
+    ],
+  },
+  testMatch: ['<rootDir>/src/**/__tests__/**/*.test.(ts|tsx)'],
+  passWithNoTests: true,
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@open-mercato/web-research-firecrawl",
+  "version": "0.7.1-develop.7194.1.ab4fc81f82",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "openMercato": {
+    "webResearchAdapter": {
+      "id": "firecrawl"
+    }
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "watch": "node watch.mjs",
+    "test": "jest --config jest.config.cjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./*.ts": {
+      "types": "./src/*.ts",
+      "default": "./dist/*.js"
+    },
+    "./*": {
+      "types": [
+        "./src/*.ts"
+      ],
+      "default": "./dist/*.js"
+    }
+  },
+  "peerDependencies": {
+    "@open-mercato/web-research": "^0.6.0"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@open-mercato/web-research": "0.7.1-develop.7194.1.ab4fc81f82",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^26.0.1",
+    "esbuild": "^0.28.1",
+    "glob": "^13.0.6",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-mercato/open-mercato",
+    "directory": "packages/web-research-firecrawl"
+  },
+  "stableVersion": "0.7.0"
+}

package/src/__tests__/firecrawl.test.ts

@@ -0,0 +1,120 @@
+import { createStubHttpClient, createTestContext, describeAdapterContract } from '@open-mercato/web-research/testing'
+import { createFirecrawlAdapter, firecrawlAdapterModule } from '../adapter'
+
+const SEARCH_BODY = JSON.stringify({
+  success: true,
+  data: [
+    {
+      url: 'https://example.com/a',
+      title: 'Alpha',
+      description: 'Alpha snippet',
+      markdown: '# Alpha\n\nBody text.',
+      publishedDate: '2026-01-01',
+    },
+    { url: 'https://example.com/b', title: 'Beta', description: 'Beta snippet' },
+  ],
+})
+
+describe('firecrawl adapter', () => {
+  it('is unavailable without an API key and never calls out', async () => {
+    const http = createStubHttpClient(() => ({ body: SEARCH_BODY }))
+    const adapter = createFirecrawlAdapter({})
+
+    const outcome = await adapter.search({ query: 'x', limit: 5 }, createTestContext({ http }))
+
+    expect(outcome).toMatchObject({ status: 'unavailable' })
+    expect(http.calls).toHaveLength(0)
+  })
+
+  it('maps search results including inline content', async () => {
+    const http = createStubHttpClient(() => ({ body: SEARCH_BODY, contentType: 'application/json' }))
+    const adapter = createFirecrawlAdapter({ apiKey: 'k' })
+
+    const outcome = await adapter.search({ query: 'x', limit: 5 }, createTestContext({ http }))
+
+    expect(outcome.status).toBe('ok')
+    if (outcome.status !== 'ok') return
+    expect(outcome.results[0]).toEqual({
+      url: 'https://example.com/a',
+      title: 'Alpha',
+      snippet: 'Alpha snippet',
+      content: '# Alpha\n\nBody text.',
+      publishedAt: '2026-01-01',
+    })
+    expect(outcome.results[1].content).toBeNull()
+  })
+
+  it('appends a site filter to the query', async () => {
+    const bodies: string[] = []
+    const http = createStubHttpClient((_url, init) => {
+      bodies.push(String(init?.body ?? ''))
+      return { body: SEARCH_BODY }
+    })
+    const adapter = createFirecrawlAdapter({ apiKey: 'k' })
+
+    await adapter.search({ query: 'pricing', limit: 5, site: 'example.com' }, createTestContext({ http }))
+
+    expect(JSON.parse(bodies[0]).query).toBe('pricing site:example.com')
+  })
+
+  it('reports an unrecognized payload as an error rather than crashing', async () => {
+    const http = createStubHttpClient(() => ({ body: '{"unexpected":true,"data":"nope"}' }))
+    const adapter = createFirecrawlAdapter({ apiKey: 'k' })
+
+    const outcome = await adapter.search({ query: 'x', limit: 5 }, createTestContext({ http }))
+
+    expect(outcome).toMatchObject({ status: 'error' })
+  })
+
+  it('returns empty rather than ok when the vendor found nothing', async () => {
+    const http = createStubHttpClient(() => ({ body: JSON.stringify({ success: true, data: [] }) }))
+    const adapter = createFirecrawlAdapter({ apiKey: 'k' })
+
+    const outcome = await adapter.search({ query: 'x', limit: 5 }, createTestContext({ http }))
+
+    expect(outcome.status).toBe('empty')
+  })
+
+  it('scrapes a page into readable text', async () => {
+    const http = createStubHttpClient(() => ({
+      body: JSON.stringify({
+        success: true,
+        data: {
+          markdown: 'Rendered content',
+          metadata: { title: 'Title', sourceURL: 'https://example.com/a', statusCode: 200 },
+        },
+      }),
+    }))
+    const adapter = createFirecrawlAdapter({ apiKey: 'k' })
+
+    const outcome = await adapter.fetch?.({ url: 'https://example.com/a' }, createTestContext({ http }))
+
+    expect(outcome).toMatchObject({
+      status: 'ok',
+      page: { title: 'Title', text: 'Rendered content', renderedWith: 'browser' },
+    })
+  })
+
+  it('sends the API key as a bearer token', async () => {
+    const seen: Array<Record<string, string> | undefined> = []
+    const http = createStubHttpClient((_url, init) => {
+      seen.push(init?.headers as Record<string, string> | undefined)
+      return { body: SEARCH_BODY }
+    })
+    const adapter = createFirecrawlAdapter({ apiKey: 'secret-key' })
+
+    await adapter.search({ query: 'x', limit: 5 }, createTestContext({ http }))
+
+    expect(seen[0]?.authorization).toBe('Bearer secret-key')
+  })
+})
+
+describeAdapterContract(
+  firecrawlAdapterModule,
+  {
+    unconfiguredOptions: {},
+    configuredOptions: { apiKey: 'test-key' },
+    context: () => createTestContext({ http: createStubHttpClient(() => ({ body: SEARCH_BODY })) }),
+  },
+  { describe, it, expect: expect as never },
+)

package/src/adapter.ts

@@ -0,0 +1,181 @@
+import {
+  CONTRACT_VERSION,
+  READY,
+  defineAdapterModule,
+  notReady,
+  searchOk,
+  stripTrailingSlashes,
+  toOutcomeFailure,
+  type AdapterContext,
+  type FetchOutcome,
+  type FetchRequest,
+  type RawResult,
+  type SearchAdapter,
+  type SearchOutcome,
+} from '@open-mercato/web-research'
+import { z } from 'zod'
+
+export const firecrawlOptionsSchema = z.object({
+  apiKey: z.string().min(1).optional(),
+  baseUrl: z.url().optional(),
+  /** Ask Firecrawl to return page content inline, sparing a second round trip. */
+  includeContent: z.boolean().optional(),
+  timeoutMs: z.number().int().min(1000).max(120_000).optional(),
+})
+
+export type FirecrawlOptions = z.infer<typeof firecrawlOptionsSchema>
+
+const DEFAULT_BASE_URL = 'https://api.firecrawl.dev'
+const DEFAULT_TIMEOUT_MS = 20_000
+
+const searchResponseSchema = z.object({
+  success: z.boolean().optional(),
+  data: z
+    .array(
+      z.object({
+        url: z.string(),
+        title: z.string().nullish(),
+        description: z.string().nullish(),
+        markdown: z.string().nullish(),
+        publishedDate: z.string().nullish(),
+      }),
+    )
+    .nullish(),
+})
+
+const scrapeResponseSchema = z.object({
+  success: z.boolean().optional(),
+  data: z
+    .object({
+      markdown: z.string().nullish(),
+      html: z.string().nullish(),
+      metadata: z
+        .object({
+          title: z.string().nullish(),
+          sourceURL: z.string().nullish(),
+          statusCode: z.number().nullish(),
+        })
+        .nullish(),
+    })
+    .nullish(),
+})
+
+function parseJson(body: string): unknown {
+  try {
+    return JSON.parse(body)
+  } catch {
+    return null
+  }
+}
+
+export function createFirecrawlAdapter(options: FirecrawlOptions): SearchAdapter {
+  const apiKey = options.apiKey?.trim() ?? ''
+  const baseUrl = stripTrailingSlashes(options.baseUrl ?? DEFAULT_BASE_URL)
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  const includeContent = options.includeContent ?? true
+
+  const post = (path: string, payload: unknown, context: AdapterContext) =>
+    context.http.request(`${baseUrl}${path}`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+      accept: ['application/json'],
+      timeoutMs,
+      signal: context.signal,
+    })
+
+  return {
+    id: 'firecrawl',
+    kind: 'api',
+    capabilities: {
+      search: true,
+      fetch: true,
+      snippets: true,
+      content: includeContent,
+      freshness: false,
+      siteFilter: true,
+      cost: 'metered',
+    },
+    /** `billable` — issues a real /v1/search query. */
+    probeCost: 'billable' as const,
+    readiness: () => (apiKey.length > 0 ? READY : notReady('Firecrawl API key is not set')),
+
+    async search(request, context): Promise<SearchOutcome> {
+      if (apiKey.length === 0) return { status: 'unavailable', reason: 'Firecrawl API key is not set' }
+      try {
+        const query = request.site ? `${request.query} site:${request.site}` : request.query
+        const response = await post(
+          '/v1/search',
+          {
+            query,
+            limit: request.limit,
+            ...(includeContent ? { scrapeOptions: { formats: ['markdown'] } } : {}),
+          },
+          context,
+        )
+        const parsed = searchResponseSchema.safeParse(parseJson(response.body))
+        if (!parsed.success) {
+          return { status: 'error', reason: 'Firecrawl returned an unrecognized response shape', retriable: false }
+        }
+        const results: RawResult[] = (parsed.data.data ?? []).map((item) => ({
+          url: item.url,
+          title: item.title ?? null,
+          snippet: item.description ?? null,
+          content: item.markdown ?? null,
+          publishedAt: item.publishedDate ?? null,
+        }))
+        context.report('ok', `Firecrawl returned ${results.length} result(s)`, { resultCount: results.length })
+        return searchOk(results)
+      } catch (error) {
+        return toOutcomeFailure(error)
+      }
+    },
+
+    async fetch(request: FetchRequest, context): Promise<FetchOutcome> {
+      if (apiKey.length === 0) return { status: 'unavailable', reason: 'Firecrawl API key is not set' }
+      try {
+        const response = await post('/v1/scrape', { url: request.url, formats: ['markdown'] }, context)
+        const parsed = scrapeResponseSchema.safeParse(parseJson(response.body))
+        const data = parsed.success ? parsed.data.data : null
+        const text = data?.markdown?.trim() ?? ''
+        if (text.length === 0) {
+          return { status: 'error', reason: 'Firecrawl returned no readable content', retriable: false }
+        }
+        return {
+          status: 'ok',
+          page: {
+            url: data?.metadata?.sourceURL ?? request.url,
+            title: data?.metadata?.title ?? null,
+            text,
+            contentType: 'text/markdown',
+            status: data?.metadata?.statusCode ?? 200,
+            truncated: false,
+            // Firecrawl renders server-side, so content that needed JavaScript
+            // arrives without us running a browser at all.
+            renderedWith: 'browser',
+          },
+        }
+      } catch (error) {
+        return toOutcomeFailure(error)
+      }
+    },
+
+    async healthCheck(context) {
+      if (apiKey.length === 0) return { ok: false, detail: 'Firecrawl API key is not set' }
+      try {
+        await post('/v1/search', { query: 'open mercato health check', limit: 1 }, context)
+        return { ok: true }
+      } catch (error) {
+        return { ok: false, detail: error instanceof Error ? error.message : String(error) }
+      }
+    },
+  }
+}
+
+export const firecrawlAdapterModule = defineAdapterModule({
+  id: 'firecrawl',
+  kind: 'api',
+  contractVersion: CONTRACT_VERSION,
+  optionsSchema: firecrawlOptionsSchema,
+  createAdapter: createFirecrawlAdapter,
+})

package/src/index.ts

@@ -0,0 +1,8 @@
+export {
+  createFirecrawlAdapter,
+  firecrawlAdapterModule,
+  firecrawlOptionsSchema,
+  type FirecrawlOptions,
+} from './adapter'
+
+export { firecrawlAdapterModule as default } from './adapter'

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/__tests__/**"]
+}

package/watch.mjs

@@ -0,0 +1,7 @@
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { watch } from '../../scripts/watch.mjs'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+watch(__dirname)