@mastra/brightdata 0.0.0

package/CHANGELOG.md

@@ -0,0 +1 @@
+# @mastra/brightdata

package/README.md

@@ -0,0 +1,106 @@
+# @mastra/brightdata
+
+[Bright Data](https://brightdata.com) web search and web fetch tools for [Mastra](https://mastra.ai) agents.
+
+Backed by the official [`@brightdata/sdk`](https://github.com/brightdata/sdk-js). Bright Data's SERP API and Web Unlocker bypass bot detection and CAPTCHAs, so the tools work on sites that block typical scrapers.
+
+## Installation
+
+```bash
+npm install @mastra/brightdata zod
+```
+
+## Quick Start
+
+Use `createBrightDataTools()` to get both tools with a shared configuration:
+
+```typescript
+import { Agent } from '@mastra/core/agent';
+import { createBrightDataTools } from '@mastra/brightdata';
+
+const tools = createBrightDataTools();
+// Or pass an explicit API token:
+// const tools = createBrightDataTools({ apiKey: 'brd_...' });
+
+const agent = new Agent({
+  id: 'realtime-information-agent',
+  name: 'Realtime Information Agent',
+  instructions:
+    'You are a realtime information agent. Use brightdata-search to find pages, and brightdata-fetch to read them.',
+  model: 'anthropic/claude-sonnet-4-6',
+  tools,
+});
+```
+
+By default the tools read `BRIGHTDATA_API_TOKEN` from your environment. You can also pass `{ apiKey }` explicitly.
+
+## Individual Tools
+
+Each tool can be created independently:
+
+```typescript
+import { createBrightDataSearchTool, createBrightDataFetchTool } from '@mastra/brightdata';
+
+const search = createBrightDataSearchTool({ apiKey: 'brd_...' });
+const fetch = createBrightDataFetchTool(); // uses BRIGHTDATA_API_TOKEN env var
+```
+
+### Web Search (`brightdata-search`)
+
+```typescript
+import { createBrightDataSearchTool } from '@mastra/brightdata';
+
+const searchTool = createBrightDataSearchTool();
+
+// When called by an agent, accepts:
+// - query (required)
+// - country: 2-letter code (e.g., 'us', 'gb')
+// - start: result offset for pagination (e.g. 10 for the second page of 10 results)
+//
+// Returns:
+// {
+//   query: string,
+//   results: Array<{ link, title, description }>,
+//   currentPage: number
+// }
+```
+
+### Web Fetch (`brightdata-fetch`)
+
+```typescript
+import { createBrightDataFetchTool } from '@mastra/brightdata';
+
+const fetchTool = createBrightDataFetchTool();
+
+// Accepts: url (required)
+// Returns: { url, content }  // content is Markdown
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | `process.env.BRIGHTDATA_API_TOKEN` | Your Bright Data API token |
+
+All tools accept the full `BrightDataClientOptions` from `@brightdata/sdk` (including `timeout`, `webUnlockerZone`, `serpZone`, `rateLimit`, etc.). If no API token is found, the tool throws a clear error at execution time.
+
+## RAG Pairing Example
+
+Combine search and fetch for retrieval-augmented generation:
+
+```typescript
+import { Agent } from '@mastra/core/agent';
+import { createBrightDataTools } from '@mastra/brightdata';
+
+const agent = new Agent({
+  id: 'rag-agent',
+  name: 'Research Assistant',
+  model: 'anthropic/claude-sonnet-4-6',
+  instructions: `You are a research assistant. Use brightdata-search to find relevant pages, then use brightdata-fetch to get full Markdown content from the best results.`,
+  tools: createBrightDataTools(),
+});
+```
+
+## License
+
+Apache-2.0

package/dist/client.d.ts

@@ -0,0 +1,6 @@
+import { bdclient } from '@brightdata/sdk';
+export type BrightDataClientOptions = ConstructorParameters<typeof bdclient>[0];
+export type BrightDataClient = bdclient;
+export declare function getBrightDataClient(config?: BrightDataClientOptions): BrightDataClient;
+export declare function closeClient(client: BrightDataClient): Promise<void>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE3C,MAAM,MAAM,uBAAuB,GAAG,qBAAqB,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AAChF,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;AAExC,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,uBAAuB,GAAG,gBAAgB,CAQtF;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CASzE"}

package/dist/fetch.d.ts

@@ -0,0 +1,8 @@
+import type { BrightDataClientOptions } from './client.js';
+export declare function createBrightDataFetchTool(config?: BrightDataClientOptions): import("@mastra/core/tools").Tool<{
+    url: string;
+}, {
+    url: string;
+    content: string;
+}, unknown, unknown, import("@mastra/core/tools").ToolExecutionContext<unknown, unknown, unknown>, "brightdata-fetch", unknown>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAW3D,wBAAgB,yBAAyB,CAAC,MAAM,CAAC,EAAE,uBAAuB;;;;;gIAuBzE"}

package/dist/index.cjs

@@ -0,0 +1,122 @@
+'use strict';
+
+var sdk = require('@brightdata/sdk');
+var tools = require('@mastra/core/tools');
+var zod = require('zod');
+
+// src/client.ts
+function getBrightDataClient(config) {
+  const apiKey = config?.apiKey ?? process.env.BRIGHTDATA_API_TOKEN;
+  if (!apiKey) {
+    throw new Error(
+      "Bright Data API token is required. Pass { apiKey } or set BRIGHTDATA_API_TOKEN env var."
+    );
+  }
+  return new sdk.bdclient({ ...config, apiKey });
+}
+async function closeClient(client) {
+  const close = client.close;
+  if (typeof close === "function") {
+    try {
+      await close.call(client);
+    } catch {
+    }
+  }
+}
+var inputSchema = zod.z.object({
+  query: zod.z.string().describe("The search query"),
+  country: zod.z.string().length(2).optional().describe('2-letter country code for geo-targeted results (e.g., "us", "gb")'),
+  start: zod.z.number().int().nonnegative().optional().describe("Result offset for pagination (e.g. 10 to get the second page of 10 results)")
+});
+var outputSchema = zod.z.object({
+  query: zod.z.string(),
+  results: zod.z.array(
+    zod.z.object({
+      link: zod.z.string(),
+      title: zod.z.string(),
+      description: zod.z.string()
+    })
+  ),
+  currentPage: zod.z.number()
+});
+function createBrightDataSearchTool(config) {
+  return tools.createTool({
+    id: "brightdata-search",
+    description: "Search Google and get back parsed organic results (link, title, description). Uses Bright Data's SERP API which bypasses bot detection. Supports country targeting and pagination via result offset.",
+    inputSchema,
+    outputSchema,
+    execute: async (input) => {
+      const client = getBrightDataClient(config);
+      try {
+        const rawResponse = await client.search.google(input.query, {
+          country: input.country,
+          start: input.start
+        });
+        const response = typeof rawResponse === "string" ? JSON.parse(rawResponse) : rawResponse;
+        const organic = Array.isArray(response.organic) ? response.organic : [];
+        const results = organic.map((entry) => {
+          if (!entry || typeof entry !== "object") return null;
+          const e = entry;
+          const link = typeof e.link === "string" ? e.link.trim() : "";
+          const title = typeof e.title === "string" ? e.title.trim() : "";
+          const description = typeof e.description === "string" ? e.description.trim() : "";
+          if (!link || !title) return null;
+          return { link, title, description };
+        }).filter((r) => r !== null);
+        const parsedPage = Number(response.current_page);
+        const currentPage = Number.isFinite(parsedPage) && parsedPage > 0 ? parsedPage : 1;
+        return {
+          query: input.query,
+          results,
+          currentPage
+        };
+      } finally {
+        await closeClient(client);
+      }
+    }
+  });
+}
+var inputSchema2 = zod.z.object({
+  url: zod.z.string().url().describe("The URL to fetch")
+});
+var outputSchema2 = zod.z.object({
+  url: zod.z.string(),
+  content: zod.z.string().describe("Page content as Markdown")
+});
+function createBrightDataFetchTool(config) {
+  return tools.createTool({
+    id: "brightdata-fetch",
+    description: "Fetch a webpage and return its content as Markdown. Uses Bright Data's Web Unlocker which bypasses bot detection and CAPTCHAs. Pass any URL, including pages that block normal scrapers.",
+    inputSchema: inputSchema2,
+    outputSchema: outputSchema2,
+    execute: async (input) => {
+      const client = getBrightDataClient(config);
+      try {
+        const content = await client.scrapeUrl(input.url, {
+          dataFormat: "markdown"
+        });
+        return {
+          url: input.url,
+          content
+        };
+      } finally {
+        await closeClient(client);
+      }
+    }
+  });
+}
+
+// src/tools.ts
+function createBrightDataTools(config) {
+  return {
+    webSearch: createBrightDataSearchTool(config),
+    webFetch: createBrightDataFetchTool(config)
+  };
+}
+
+exports.createBrightDataFetchTool = createBrightDataFetchTool;
+exports.createBrightDataSearchTool = createBrightDataSearchTool;
+exports.createBrightDataTools = createBrightDataTools;
+exports.getBrightDataClient = getBrightDataClient;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts","../src/search.ts","../src/fetch.ts","../src/tools.ts"],"names":["bdclient","z","createTool","inputSchema","outputSchema"],"mappings":"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","file":"index.cjs","sourcesContent":["import { bdclient } from '@brightdata/sdk';\n\nexport type BrightDataClientOptions = ConstructorParameters<typeof bdclient>[0];\nexport type BrightDataClient = bdclient;\n\nexport function getBrightDataClient(config?: BrightDataClientOptions): BrightDataClient {\n  const apiKey = config?.apiKey ?? process.env.BRIGHTDATA_API_TOKEN;\n  if (!apiKey) {\n    throw new Error(\n      'Bright Data API token is required. Pass { apiKey } or set BRIGHTDATA_API_TOKEN env var.',\n    );\n  }\n  return new bdclient({ ...config, apiKey });\n}\n\nexport async function closeClient(client: BrightDataClient): Promise<void> {\n  const close = (client as { close?: () => Promise<void> | void }).close;\n  if (typeof close === 'function') {\n    try {\n      await close.call(client);\n    } catch {\n      // best-effort cleanup; never mask the primary tool error from the finally block\n    }\n  }\n}\n","import { createTool } from '@mastra/core/tools';\nimport { z } from 'zod';\n\nimport { closeClient, getBrightDataClient } from './client.js';\nimport type { BrightDataClientOptions } from './client.js';\n\nconst inputSchema = z.object({\n  query: z.string().describe('The search query'),\n  country: z\n    .string()\n    .length(2)\n    .optional()\n    .describe('2-letter country code for geo-targeted results (e.g., \"us\", \"gb\")'),\n  start: z\n    .number()\n    .int()\n    .nonnegative()\n    .optional()\n    .describe('Result offset for pagination (e.g. 10 to get the second page of 10 results)'),\n});\n\nconst outputSchema = z.object({\n  query: z.string(),\n  results: z.array(\n    z.object({\n      link: z.string(),\n      title: z.string(),\n      description: z.string(),\n    }),\n  ),\n  currentPage: z.number(),\n});\n\nexport function createBrightDataSearchTool(config?: BrightDataClientOptions) {\n  return createTool({\n    id: 'brightdata-search',\n    description:\n      \"Search Google and get back parsed organic results (link, title, description). Uses Bright Data's SERP API which bypasses bot detection. Supports country targeting and pagination via result offset.\",\n    inputSchema,\n    outputSchema,\n    execute: async input => {\n      const client = getBrightDataClient(config);\n      try {\n        const rawResponse = await client.search.google(input.query, {\n          country: input.country,\n          start: input.start,\n        });\n\n        const response: { organic?: unknown; current_page?: unknown } =\n          typeof rawResponse === 'string' ? JSON.parse(rawResponse) : rawResponse;\n\n        const organic = Array.isArray(response.organic) ? response.organic : [];\n        const results = organic\n          .map((entry: unknown) => {\n            if (!entry || typeof entry !== 'object') return null;\n            const e = entry as Record<string, unknown>;\n            const link = typeof e.link === 'string' ? e.link.trim() : '';\n            const title = typeof e.title === 'string' ? e.title.trim() : '';\n            const description = typeof e.description === 'string' ? e.description.trim() : '';\n            if (!link || !title) return null;\n            return { link, title, description };\n          })\n          .filter((r): r is { link: string; title: string; description: string } => r !== null);\n\n        const parsedPage = Number(response.current_page);\n        const currentPage = Number.isFinite(parsedPage) && parsedPage > 0 ? parsedPage : 1;\n\n        return {\n          query: input.query,\n          results,\n          currentPage,\n        };\n      } finally {\n        await closeClient(client);\n      }\n    },\n  });\n}\n","import { createTool } from '@mastra/core/tools';\nimport { z } from 'zod';\n\nimport { closeClient, getBrightDataClient } from './client.js';\nimport type { BrightDataClientOptions } from './client.js';\n\nconst inputSchema = z.object({\n  url: z.string().url().describe('The URL to fetch'),\n});\n\nconst outputSchema = z.object({\n  url: z.string(),\n  content: z.string().describe('Page content as Markdown'),\n});\n\nexport function createBrightDataFetchTool(config?: BrightDataClientOptions) {\n  return createTool({\n    id: 'brightdata-fetch',\n    description:\n      \"Fetch a webpage and return its content as Markdown. Uses Bright Data's Web Unlocker which bypasses bot detection and CAPTCHAs. Pass any URL, including pages that block normal scrapers.\",\n    inputSchema,\n    outputSchema,\n    execute: async input => {\n      const client = getBrightDataClient(config);\n      try {\n        const content = await client.scrapeUrl(input.url, {\n          dataFormat: 'markdown',\n        });\n\n        return {\n          url: input.url,\n          content,\n        };\n      } finally {\n        await closeClient(client);\n      }\n    },\n  });\n}\n","import type { BrightDataClientOptions } from './client.js';\nimport { createBrightDataFetchTool } from './fetch.js';\nimport { createBrightDataSearchTool } from './search.js';\n\nexport function createBrightDataTools(config?: BrightDataClientOptions) {\n  return {\n    webSearch: createBrightDataSearchTool(config),\n    webFetch: createBrightDataFetchTool(config),\n  };\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { getBrightDataClient, type BrightDataClientOptions, type BrightDataClient } from './client.js';
+export { createBrightDataSearchTool } from './search.js';
+export { createBrightDataFetchTool } from './fetch.js';
+export { createBrightDataTools } from './tools.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,uBAAuB,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACvG,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,117 @@
+import { bdclient } from '@brightdata/sdk';
+import { createTool } from '@mastra/core/tools';
+import { z } from 'zod';
+
+// src/client.ts
+function getBrightDataClient(config) {
+  const apiKey = config?.apiKey ?? process.env.BRIGHTDATA_API_TOKEN;
+  if (!apiKey) {
+    throw new Error(
+      "Bright Data API token is required. Pass { apiKey } or set BRIGHTDATA_API_TOKEN env var."
+    );
+  }
+  return new bdclient({ ...config, apiKey });
+}
+async function closeClient(client) {
+  const close = client.close;
+  if (typeof close === "function") {
+    try {
+      await close.call(client);
+    } catch {
+    }
+  }
+}
+var inputSchema = z.object({
+  query: z.string().describe("The search query"),
+  country: z.string().length(2).optional().describe('2-letter country code for geo-targeted results (e.g., "us", "gb")'),
+  start: z.number().int().nonnegative().optional().describe("Result offset for pagination (e.g. 10 to get the second page of 10 results)")
+});
+var outputSchema = z.object({
+  query: z.string(),
+  results: z.array(
+    z.object({
+      link: z.string(),
+      title: z.string(),
+      description: z.string()
+    })
+  ),
+  currentPage: z.number()
+});
+function createBrightDataSearchTool(config) {
+  return createTool({
+    id: "brightdata-search",
+    description: "Search Google and get back parsed organic results (link, title, description). Uses Bright Data's SERP API which bypasses bot detection. Supports country targeting and pagination via result offset.",
+    inputSchema,
+    outputSchema,
+    execute: async (input) => {
+      const client = getBrightDataClient(config);
+      try {
+        const rawResponse = await client.search.google(input.query, {
+          country: input.country,
+          start: input.start
+        });
+        const response = typeof rawResponse === "string" ? JSON.parse(rawResponse) : rawResponse;
+        const organic = Array.isArray(response.organic) ? response.organic : [];
+        const results = organic.map((entry) => {
+          if (!entry || typeof entry !== "object") return null;
+          const e = entry;
+          const link = typeof e.link === "string" ? e.link.trim() : "";
+          const title = typeof e.title === "string" ? e.title.trim() : "";
+          const description = typeof e.description === "string" ? e.description.trim() : "";
+          if (!link || !title) return null;
+          return { link, title, description };
+        }).filter((r) => r !== null);
+        const parsedPage = Number(response.current_page);
+        const currentPage = Number.isFinite(parsedPage) && parsedPage > 0 ? parsedPage : 1;
+        return {
+          query: input.query,
+          results,
+          currentPage
+        };
+      } finally {
+        await closeClient(client);
+      }
+    }
+  });
+}
+var inputSchema2 = z.object({
+  url: z.string().url().describe("The URL to fetch")
+});
+var outputSchema2 = z.object({
+  url: z.string(),
+  content: z.string().describe("Page content as Markdown")
+});
+function createBrightDataFetchTool(config) {
+  return createTool({
+    id: "brightdata-fetch",
+    description: "Fetch a webpage and return its content as Markdown. Uses Bright Data's Web Unlocker which bypasses bot detection and CAPTCHAs. Pass any URL, including pages that block normal scrapers.",
+    inputSchema: inputSchema2,
+    outputSchema: outputSchema2,
+    execute: async (input) => {
+      const client = getBrightDataClient(config);
+      try {
+        const content = await client.scrapeUrl(input.url, {
+          dataFormat: "markdown"
+        });
+        return {
+          url: input.url,
+          content
+        };
+      } finally {
+        await closeClient(client);
+      }
+    }
+  });
+}
+
+// src/tools.ts
+function createBrightDataTools(config) {
+  return {
+    webSearch: createBrightDataSearchTool(config),
+    webFetch: createBrightDataFetchTool(config)
+  };
+}
+
+export { createBrightDataFetchTool, createBrightDataSearchTool, createBrightDataTools, getBrightDataClient };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts","../src/search.ts","../src/fetch.ts","../src/tools.ts"],"names":["inputSchema","z","outputSchema","createTool"],"mappings":"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","file":"index.js","sourcesContent":["import { bdclient } from '@brightdata/sdk';\n\nexport type BrightDataClientOptions = ConstructorParameters<typeof bdclient>[0];\nexport type BrightDataClient = bdclient;\n\nexport function getBrightDataClient(config?: BrightDataClientOptions): BrightDataClient {\n  const apiKey = config?.apiKey ?? process.env.BRIGHTDATA_API_TOKEN;\n  if (!apiKey) {\n    throw new Error(\n      'Bright Data API token is required. Pass { apiKey } or set BRIGHTDATA_API_TOKEN env var.',\n    );\n  }\n  return new bdclient({ ...config, apiKey });\n}\n\nexport async function closeClient(client: BrightDataClient): Promise<void> {\n  const close = (client as { close?: () => Promise<void> | void }).close;\n  if (typeof close === 'function') {\n    try {\n      await close.call(client);\n    } catch {\n      // best-effort cleanup; never mask the primary tool error from the finally block\n    }\n  }\n}\n","import { createTool } from '@mastra/core/tools';\nimport { z } from 'zod';\n\nimport { closeClient, getBrightDataClient } from './client.js';\nimport type { BrightDataClientOptions } from './client.js';\n\nconst inputSchema = z.object({\n  query: z.string().describe('The search query'),\n  country: z\n    .string()\n    .length(2)\n    .optional()\n    .describe('2-letter country code for geo-targeted results (e.g., \"us\", \"gb\")'),\n  start: z\n    .number()\n    .int()\n    .nonnegative()\n    .optional()\n    .describe('Result offset for pagination (e.g. 10 to get the second page of 10 results)'),\n});\n\nconst outputSchema = z.object({\n  query: z.string(),\n  results: z.array(\n    z.object({\n      link: z.string(),\n      title: z.string(),\n      description: z.string(),\n    }),\n  ),\n  currentPage: z.number(),\n});\n\nexport function createBrightDataSearchTool(config?: BrightDataClientOptions) {\n  return createTool({\n    id: 'brightdata-search',\n    description:\n      \"Search Google and get back parsed organic results (link, title, description). Uses Bright Data's SERP API which bypasses bot detection. Supports country targeting and pagination via result offset.\",\n    inputSchema,\n    outputSchema,\n    execute: async input => {\n      const client = getBrightDataClient(config);\n      try {\n        const rawResponse = await client.search.google(input.query, {\n          country: input.country,\n          start: input.start,\n        });\n\n        const response: { organic?: unknown; current_page?: unknown } =\n          typeof rawResponse === 'string' ? JSON.parse(rawResponse) : rawResponse;\n\n        const organic = Array.isArray(response.organic) ? response.organic : [];\n        const results = organic\n          .map((entry: unknown) => {\n            if (!entry || typeof entry !== 'object') return null;\n            const e = entry as Record<string, unknown>;\n            const link = typeof e.link === 'string' ? e.link.trim() : '';\n            const title = typeof e.title === 'string' ? e.title.trim() : '';\n            const description = typeof e.description === 'string' ? e.description.trim() : '';\n            if (!link || !title) return null;\n            return { link, title, description };\n          })\n          .filter((r): r is { link: string; title: string; description: string } => r !== null);\n\n        const parsedPage = Number(response.current_page);\n        const currentPage = Number.isFinite(parsedPage) && parsedPage > 0 ? parsedPage : 1;\n\n        return {\n          query: input.query,\n          results,\n          currentPage,\n        };\n      } finally {\n        await closeClient(client);\n      }\n    },\n  });\n}\n","import { createTool } from '@mastra/core/tools';\nimport { z } from 'zod';\n\nimport { closeClient, getBrightDataClient } from './client.js';\nimport type { BrightDataClientOptions } from './client.js';\n\nconst inputSchema = z.object({\n  url: z.string().url().describe('The URL to fetch'),\n});\n\nconst outputSchema = z.object({\n  url: z.string(),\n  content: z.string().describe('Page content as Markdown'),\n});\n\nexport function createBrightDataFetchTool(config?: BrightDataClientOptions) {\n  return createTool({\n    id: 'brightdata-fetch',\n    description:\n      \"Fetch a webpage and return its content as Markdown. Uses Bright Data's Web Unlocker which bypasses bot detection and CAPTCHAs. Pass any URL, including pages that block normal scrapers.\",\n    inputSchema,\n    outputSchema,\n    execute: async input => {\n      const client = getBrightDataClient(config);\n      try {\n        const content = await client.scrapeUrl(input.url, {\n          dataFormat: 'markdown',\n        });\n\n        return {\n          url: input.url,\n          content,\n        };\n      } finally {\n        await closeClient(client);\n      }\n    },\n  });\n}\n","import type { BrightDataClientOptions } from './client.js';\nimport { createBrightDataFetchTool } from './fetch.js';\nimport { createBrightDataSearchTool } from './search.js';\n\nexport function createBrightDataTools(config?: BrightDataClientOptions) {\n  return {\n    webSearch: createBrightDataSearchTool(config),\n    webFetch: createBrightDataFetchTool(config),\n  };\n}\n"]}

package/dist/search.d.ts

@@ -0,0 +1,15 @@
+import type { BrightDataClientOptions } from './client.js';
+export declare function createBrightDataSearchTool(config?: BrightDataClientOptions): import("@mastra/core/tools").Tool<{
+    query: string;
+    country?: string | undefined;
+    start?: number | undefined;
+}, {
+    query: string;
+    results: {
+        link: string;
+        title: string;
+        description: string;
+    }[];
+    currentPage: number;
+}, unknown, unknown, import("@mastra/core/tools").ToolExecutionContext<unknown, unknown, unknown>, "brightdata-search", unknown>;
+//# sourceMappingURL=search.d.ts.map

package/dist/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AA6B3D,wBAAgB,0BAA0B,CAAC,MAAM,CAAC,EAAE,uBAAuB;;;;;;;;;;;;iIA4C1E"}

package/dist/tools.d.ts

@@ -0,0 +1,23 @@
+import type { BrightDataClientOptions } from './client.js';
+export declare function createBrightDataTools(config?: BrightDataClientOptions): {
+    webSearch: import("@mastra/core/tools").Tool<{
+        query: string;
+        country?: string | undefined;
+        start?: number | undefined;
+    }, {
+        query: string;
+        results: {
+            link: string;
+            title: string;
+            description: string;
+        }[];
+        currentPage: number;
+    }, unknown, unknown, import("@mastra/core/tools").ToolExecutionContext<unknown, unknown, unknown>, "brightdata-search", unknown>;
+    webFetch: import("@mastra/core/tools").Tool<{
+        url: string;
+    }, {
+        url: string;
+        content: string;
+    }, unknown, unknown, import("@mastra/core/tools").ToolExecutionContext<unknown, unknown, unknown>, "brightdata-fetch", unknown>;
+};
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAI3D,wBAAgB,qBAAqB,CAAC,MAAM,CAAC,EAAE,uBAAuB;;;;;;;;;;;;;;;;;;;;EAKrE"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@mastra/brightdata",
+  "version": "0.0.0",
+  "description": "Bright Data web search and web fetch tools for Mastra agents",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build:lib": "tsup --silent --config tsup.config.ts",
+    "build:watch": "pnpm build:lib --watch",
+    "lint": "eslint .",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "mastra",
+    "brightdata",
+    "brightdata-search",
+    "brightdata-fetch",
+    "tools",
+    "ai-agent"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mastra-ai/mastra.git",
+    "directory": "integrations/brightdata"
+  },
+  "bugs": {
+    "url": "https://github.com/mastra-ai/mastra/issues"
+  },
+  "homepage": "https://mastra.ai",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "dependencies": {
+    "@brightdata/sdk": "^1.1.0"
+  },
+  "peerDependencies": {
+    "@mastra/core": ">=1.0.0-0 <2.0.0-0",
+    "zod": ">=3.0.0"
+  },
+  "devDependencies": {
+    "@internal/lint": "workspace:*",
+    "@internal/types-builder": "workspace:*",
+    "@mastra/core": "workspace:*",
+    "tsup": "^8.5.1",
+    "typescript": "catalog:",
+    "vitest": "catalog:",
+    "zod": "catalog:"
+  }
+}