Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

fix(sdk): add helpful error when agents access SearchData.data

Himadri M645613fae407
diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/search-data-property.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/search-data-property.test.ts
new file mode 100644
index 000000000..966728b6c
--- /dev/null
+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/search-data-property.test.ts
@@ -0,0 +1,66 @@
+import { search } from "../../../v2/methods/search";
+
+const fakeHttp = {
+ post: jest.fn(),
+} as any;
+
+describe("SearchData .data helpful error", () => {
+ beforeEach(() => jest.clearAllMocks());
+
+ it("throws with available sources when .data is accessed", async () => {
+ fakeHttp.post.mockResolvedValue({
+ status: 200,
+ data: {
+ success: true,
+ data: {
+ web: [{ title: "Test", url: "http://a.com" }],
+ },
+ },
+ });
+
+ const result = await search(fakeHttp, { query: "test" });
+ expect(result.web).toHaveLength(1);
+ expect(() => (result as any).data).toThrow(
+ /SearchData has no '\.data'.*\.web \(1 results\)/,
+ );
+ });
+
+ it("throws with multiple sources listed", async () => {
+ fakeHttp.post.mockResolvedValue({
+ status: 200,
+ data: {
+ success: true,
+ data: {
+ web: [{ title: "W", url: "http://a.com" }],
+ news: [{ title: "N", url: "http://b.com" }],
+ },
+ },
+ });
+
+ const result = await search(fakeHttp, { query: "test" });
+ expect(() => (result as any).data).toThrow(/\.web.*\.news/);
+ });
+
+ it("throws with generic message when empty", async () => {
+ fakeHttp.post.mockResolvedValue({
+ status: 200,
+ data: { success: true, data: {} },
+ });
+
+ const result = await search(fakeHttp, { query: "test" });
+ expect(() => (result as any).data).toThrow("grouped by source");
+ });
+
+ it("does not show .data in Object.keys", async () => {
+ fakeHttp.post.mockResolvedValue({
+ status: 200,
+ data: {
+ success: true,
+ data: { web: [{ title: "T", url: "http://a.com" }] },
+ },
+ });
+
+ const result = await search(fakeHttp, { query: "test" });
+ expect(Object.keys(result)).not.toContain("data");
+ });
+});
diff --git a/apps/js-sdk/firecrawl/src/v2/methods/search.ts b/apps/js-sdk/firecrawl/src/v2/methods/search.ts
index 0d1b54b8c..1b002db68 100644
--- a/apps/js-sdk/firecrawl/src/v2/methods/search.ts
+++ b/apps/js-sdk/firecrawl/src/v2/methods/search.ts
@@ -98,6 +98,20 @@ export async function search(
if (data.news) out.news = transformArray<SearchResultNews>(data.news);
if (data.images)
out.images = transformArray<SearchResultImages>(data.images);
+ Object.defineProperty(out, "data", {
+ get() {
+ const parts: string[] = [];
+ if (out.web?.length) parts.push(`.web (${out.web.length} results)`);
+ if (out.news?.length) parts.push(`.news (${out.news.length} results)`);
+ if (out.images?.length) parts.push(`.images (${out.images.length} results)`);
+ const available = parts.length ? parts.join(", ") : ".web, .news, or .images";
+ throw new Error(
+ `SearchData has no '.data'. Results are grouped by source: ${available}`,
+ );
+ },
+ enumerable: false,
+ configurable: true,
+ });
return out;
} catch (err: any) {
if (err?.isAxiosError) return normalizeAxiosError(err, "search");
diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.py
index 372ab6566..3862cd8aa 100644
--- a/apps/python-sdk/firecrawl/v2/types.py
+++ b/apps/python-sdk/firecrawl/v2/types.py
@@ -1362,6 +1362,20 @@ class SearchData(BaseModel):
news: Optional[List[Union[SearchResultNews, Document]]] = None
images: Optional[List[Union[SearchResultImages, Document]]] = None
+ @property
+ def data(self):
+ parts = []
+ if self.web:
+ parts.append(f".web ({len(self.web)} results)")
+ if self.news:
+ parts.append(f".news ({len(self.news)} results)")
+ if self.images:
+ parts.append(f".images ({len(self.images)} results)")
+ available = ", ".join(parts) if parts else ".web, .news, or .images"
+ raise AttributeError(
+ f"SearchData has no '.data'. Results are grouped by source: {available}"
+ )
+
class SearchResponse(BaseResponse[SearchData]):
"""Response from search operation."""
diff --git a/apps/python-sdk/tests/test_search_data_property.py b/apps/python-sdk/tests/test_search_data_property.py
new file mode 100644
index 000000000..b86854e13
--- /dev/null
+++ b/apps/python-sdk/tests/test_search_data_property.py
@@ -0,0 +1,27 @@
+import pytest
+from firecrawl.v2.types import SearchData, SearchResultWeb, SearchResultNews
+
+
+class TestSearchDataDotData:
+ def test_raises_with_web_results(self):
+ sd = SearchData(web=[SearchResultWeb(title="T", url="http://a.com")])
+ with pytest.raises(AttributeError, match=r"\.web \(1 results\)"):
+ sd.data
+
+ def test_raises_with_multiple_sources(self):
+ sd = SearchData(
+ web=[SearchResultWeb(title="T", url="http://a.com")],
+ news=[SearchResultNews(title="N", url="http://b.com")],
+ )
+ with pytest.raises(AttributeError, match=r"\.web.*\.news"):
+ sd.data
+
+ def test_raises_with_empty_response(self):
+ sd = SearchData()
+ with pytest.raises(AttributeError, match="grouped by source"):
+ sd.data
+
+ def test_web_still_works(self):
+ sd = SearchData(web=[SearchResultWeb(title="T", url="http://a.com")])
+ assert len(sd.web) == 1
+ assert sd.web[0].title == "T"