@mrscraper/ai-sdk 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 MrScraper
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,76 @@
1
- # Temporary Holding Version
1
+ # MrScraper tools for the AI SDK
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [MrScraper](https://mrscraper.com) tools for the [Vercel AI SDK](https://ai-sdk.dev):
4
+ retrieve public web pages as Markdown, HTML, or screenshots, search the web, and
5
+ check your MrScraper plan and token usage.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ npm install @mrscraper/ai-sdk ai zod
11
+ ```
12
+
13
+ Requires AI SDK 7 and Node.js 18 or later. Get an API key at
14
+ [app.mrscraper.com/api-tokens](https://app.mrscraper.com/api-tokens) and set it
15
+ as `MRSCRAPER_API_KEY` (or pass `apiKey` to the tool factories).
16
+
17
+ ## Use
18
+
19
+ ```ts
20
+ import { generateText, isStepCount } from "ai";
21
+ import { mrscraperTools } from "@mrscraper/ai-sdk";
22
+
23
+ const { text } = await generateText({
24
+ model: "openai/gpt-5",
25
+ prompt:
26
+ "Read https://www.scrapethissite.com/pages/simple/ and list the five countries with the largest area.",
27
+ tools: mrscraperTools(),
28
+ stopWhen: isStepCount(5),
29
+ });
30
+
31
+ console.log(text);
32
+ ```
33
+
34
+ Pick individual tools when you only need some of them:
35
+
36
+ ```ts
37
+ import { scraperApiTool, webSearchTool } from "@mrscraper/ai-sdk";
38
+
39
+ const tools = {
40
+ scraperAPI: scraperApiTool({ apiKey: process.env.MRSCRAPER_API_KEY }),
41
+ webSearch: webSearchTool(),
42
+ };
43
+ ```
44
+
45
+ ## Tools
46
+
47
+ | Tool | Factory | What it does |
48
+ | --- | --- | --- |
49
+ | `scraperAPI` | `scraperApiTool()` | Retrieves a known public page as Markdown (default), HTML, a screenshot, or a combination. Renders JavaScript-heavy pages in a browser when needed. Inputs: `url`, `formats`, `browserRendering`, `waitForSelector`, `geoCode`, `timeout`. |
50
+ | `webSearch` | `webSearchTool()` | Searches the web and returns parsed organic results (`rank`, `title`, `link`, `description`, `source`), "People also ask" entries, and the next page number. Inputs: `query` (text or a search results URL), `region`, `language`, `page`. |
51
+ | `status` | `accountStatusTool()` | Returns the subscription status, token limit, tokens used, and tokens remaining. Uses no tokens. |
52
+
53
+ `scraperAPI` sends screenshots to the model as image parts instead of base64
54
+ text, so a screenshot costs image tokens rather than hundreds of thousands of
55
+ text tokens. Other results are sent as JSON.
56
+
57
+ `scraperAPI` and `webSearch` use tokens from your MrScraper plan. Errors from
58
+ the API (for example an invalid key) are thrown from the tool and reported to
59
+ the model as tool errors; the key never appears in the error.
60
+
61
+ ## Data and permissions
62
+
63
+ The tools send target URLs, search queries, and request options to MrScraper's
64
+ API. Use them only for public or otherwise authorized content, and follow the
65
+ target site's terms. See the [Privacy Policy](https://mrscraper.com/privacy-policy)
66
+ and [Acceptable Use Policy](https://mrscraper.com/acceptable-use-policy).
67
+
68
+ ## Links
69
+
70
+ - Documentation: https://docs.mrscraper.com/docs/integrations/vercel-ai-sdk
71
+ - MrScraper MCP server (for MCP clients): https://github.com/mrscraper-com/mrscraper-mcp
72
+ - Support: support@mrscraper.com
73
+
74
+ ## License
75
+
76
+ [MIT](LICENSE)
@@ -0,0 +1,44 @@
1
+ import { type AccountSummary } from "@mrscraper/sdk";
2
+ import { type Tool } from "ai";
3
+ import { type PageFormat, type PageResult, type SearchResult } from "./results.js";
4
+ export type { AccountSummary } from "@mrscraper/sdk";
5
+ export type { PageFormat, PageResult, SearchResult, SearchResultItem, } from "./results.js";
6
+ /** Input of the scraperAPI tool after validation. */
7
+ export interface ScraperApiInput {
8
+ url: string;
9
+ formats: PageFormat[];
10
+ browserRendering?: boolean;
11
+ waitForSelector?: string;
12
+ geoCode?: string;
13
+ timeout?: number;
14
+ }
15
+ /** Input of the webSearch tool after validation. */
16
+ export interface WebSearchInput {
17
+ query: string;
18
+ region?: string;
19
+ language?: string;
20
+ page?: number;
21
+ }
22
+ export interface MrScraperToolOptions {
23
+ /**
24
+ * MrScraper API key from https://app.mrscraper.com/api-tokens. Defaults to
25
+ * the MRSCRAPER_API_KEY environment variable, then MRSCRAPER_API_TOKEN.
26
+ */
27
+ apiKey?: string;
28
+ }
29
+ /**
30
+ * Retrieves a known public page as Markdown, HTML, a screenshot, or a
31
+ * combination through MrScraper's Scraper API.
32
+ */
33
+ export declare function scraperApiTool(options?: MrScraperToolOptions): Tool<ScraperApiInput, PageResult>;
34
+ /** Searches the web through MrScraper and returns parsed organic results. */
35
+ export declare function webSearchTool(options?: MrScraperToolOptions): Tool<WebSearchInput, SearchResult>;
36
+ /** Reports the MrScraper plan, token usage, and remaining tokens. */
37
+ export declare function accountStatusTool(options?: MrScraperToolOptions): Tool<Record<string, never>, AccountSummary>;
38
+ /** All MrScraper tools, keyed by the names the MrScraper MCP server uses. */
39
+ export declare function mrscraperTools(options?: MrScraperToolOptions): {
40
+ scraperAPI: Tool<ScraperApiInput, PageResult>;
41
+ webSearch: Tool<WebSearchInput, SearchResult>;
42
+ status: Tool<Record<string, never>, AccountSummary>;
43
+ };
44
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACvF,OAAO,EAAQ,KAAK,IAAI,EAAE,MAAM,IAAI,CAAC;AAGrC,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAEtB,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,YAAY,EACV,UAAU,EACV,UAAU,EACV,YAAY,EACZ,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAQD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,oBAAyB,GAAG,IAAI,CAAC,eAAe,EAAE,UAAU,CAAC,CAmDpG;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,IAAI,CAAC,cAAc,EAAE,YAAY,CAAC,CAoCpG;AAED,qEAAqE;AACrE,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,oBAAyB,GACjC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,cAAc,CAAC,CAW7C;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,OAAO,GAAE,oBAAyB,GAAG;IAClE,UAAU,EAAE,IAAI,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;IAC9C,SAAS,EAAE,IAAI,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC;IAC9C,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,cAAc,CAAC,CAAC;CACrD,CAMA"}
package/dist/index.js ADDED
@@ -0,0 +1,121 @@
1
+ import { account, scraper_api, web_search } from "@mrscraper/sdk";
2
+ import { tool } from "ai";
3
+ import { z } from "zod/v4";
4
+ import { toPageModelOutput, toPageResult, toSearchResult, } from "./results.js";
5
+ function apiKey(options) {
6
+ return options.apiKey ?? process.env.MRSCRAPER_API_KEY ?? undefined;
7
+ }
8
+ const formatSchema = z.enum(["markdown", "html", "screenshot"]);
9
+ /**
10
+ * Retrieves a known public page as Markdown, HTML, a screenshot, or a
11
+ * combination through MrScraper's Scraper API.
12
+ */
13
+ export function scraperApiTool(options = {}) {
14
+ return tool({
15
+ description: "Retrieve a known public web page through MrScraper as Markdown, HTML, a screenshot, or a combination. " +
16
+ "Use Markdown for reading and summarizing; add html when exact markup or attributes matter. " +
17
+ "MrScraper renders JavaScript-heavy pages in a browser when needed. Each call uses MrScraper plan tokens.",
18
+ inputSchema: z.object({
19
+ url: z.url({ protocol: /^https?$/ }).describe("Absolute http or https URL of the page."),
20
+ formats: z
21
+ .array(formatSchema)
22
+ .min(1)
23
+ .default(["markdown"])
24
+ .describe("Representations to return. Defaults to markdown."),
25
+ browserRendering: z
26
+ .boolean()
27
+ .optional()
28
+ .describe("true forces a real browser, false disables it; omit for automatic fallback."),
29
+ waitForSelector: z
30
+ .string()
31
+ .min(1)
32
+ .optional()
33
+ .describe("CSS selector to wait for before the page is captured."),
34
+ geoCode: z
35
+ .string()
36
+ .length(2)
37
+ .optional()
38
+ .describe("Two-letter country code for the request location, such as US or GB."),
39
+ timeout: z
40
+ .number()
41
+ .int()
42
+ .min(1)
43
+ .max(300)
44
+ .optional()
45
+ .describe("Page timeout in seconds, 1 to 300. Defaults to 120."),
46
+ }),
47
+ async execute({ url, formats, browserRendering, waitForSelector, geoCode, timeout }) {
48
+ const requested = new Set(formats);
49
+ const response = await scraper_api(url, {
50
+ token: apiKey(options),
51
+ markdown: requested.has("markdown"),
52
+ html: requested.has("html"),
53
+ screenshot: requested.has("screenshot"),
54
+ browser_rendering: browserRendering ?? null,
55
+ wait_for_selector: waitForSelector ?? null,
56
+ ...(geoCode === undefined ? {} : { geo_code: geoCode.toUpperCase() }),
57
+ ...(timeout === undefined ? {} : { timeout }),
58
+ });
59
+ return toPageResult(url, [...requested], response);
60
+ },
61
+ toModelOutput: ({ output }) => toPageModelOutput(output),
62
+ });
63
+ }
64
+ /** Searches the web through MrScraper and returns parsed organic results. */
65
+ export function webSearchTool(options = {}) {
66
+ return tool({
67
+ description: "Search the web through MrScraper and get parsed organic results (rank, title, link, description, source). " +
68
+ "Use it to discover pages when no URL is known, then retrieve chosen pages with the scraperAPI tool. " +
69
+ "Each call uses MrScraper plan tokens.",
70
+ inputSchema: z.object({
71
+ query: z
72
+ .string()
73
+ .min(1)
74
+ .describe("Search terms, or a complete search results URL."),
75
+ region: z
76
+ .string()
77
+ .length(2)
78
+ .optional()
79
+ .describe("Two-letter country code for the results, such as us, gb, or id."),
80
+ language: z
81
+ .string()
82
+ .min(2)
83
+ .max(5)
84
+ .optional()
85
+ .describe("Language code for the results, such as en or id."),
86
+ page: z.number().int().min(1).optional().describe("One-based result page."),
87
+ }),
88
+ async execute({ query, region, language, page }) {
89
+ const response = await web_search(query, {
90
+ token: apiKey(options),
91
+ raw: false,
92
+ format: "json",
93
+ region: region ?? null,
94
+ language: language ?? null,
95
+ page: page ?? null,
96
+ });
97
+ return toSearchResult(query, response);
98
+ },
99
+ });
100
+ }
101
+ /** Reports the MrScraper plan, token usage, and remaining tokens. */
102
+ export function accountStatusTool(options = {}) {
103
+ return tool({
104
+ description: "Show the connected MrScraper account's subscription status, token limit, tokens used, and tokens remaining. " +
105
+ "Uses no tokens.",
106
+ inputSchema: z.object({}),
107
+ async execute() {
108
+ const response = await account({ token: apiKey(options) });
109
+ return response.data;
110
+ },
111
+ });
112
+ }
113
+ /** All MrScraper tools, keyed by the names the MrScraper MCP server uses. */
114
+ export function mrscraperTools(options = {}) {
115
+ return {
116
+ scraperAPI: scraperApiTool(options),
117
+ webSearch: webSearchTool(options),
118
+ status: accountStatusTool(options),
119
+ };
120
+ }
121
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,75 @@
1
+ /** Page formats the scraperAPI tool can return. */
2
+ export type PageFormat = "markdown" | "html" | "screenshot";
3
+ /** What the scraperAPI tool returns for one page. */
4
+ export interface PageResult {
5
+ url: string;
6
+ /** HTTP status of the MrScraper API response, not of the target page. */
7
+ statusCode: number;
8
+ markdown?: string;
9
+ html?: string;
10
+ /**
11
+ * Base64-encoded image (PNG or JPEG, depending on the page). Sent to the
12
+ * model as an image, not as text.
13
+ */
14
+ screenshot?: string;
15
+ /** MrScraper tokens this request used, when the API reports it. */
16
+ tokenUsage?: number;
17
+ /** Error the API reported alongside a successful response. */
18
+ error?: string;
19
+ }
20
+ /** One organic search result. */
21
+ export interface SearchResultItem {
22
+ rank?: number;
23
+ title?: string;
24
+ link?: string;
25
+ description?: string;
26
+ source?: string;
27
+ }
28
+ /** What the webSearch tool returns. */
29
+ export interface SearchResult {
30
+ query: string;
31
+ results: SearchResultItem[];
32
+ /** "People also ask" entries as the API returns them; omitted when empty. */
33
+ peopleAlsoAsk?: unknown[];
34
+ /** Next result page number, or null when the search reports no further page. */
35
+ nextPage: number | null;
36
+ }
37
+ interface ApiResponse {
38
+ status_code: number;
39
+ data: unknown;
40
+ }
41
+ /**
42
+ * Keeps the requested formats the API returned, plus usage and errors.
43
+ *
44
+ * When only HTML is requested, the API proxies the page and answers with the
45
+ * raw HTML string instead of a JSON object; that string is the html format.
46
+ */
47
+ export declare function toPageResult(url: string, formats: readonly PageFormat[], response: ApiResponse): PageResult;
48
+ /** Reduces the parsed search response to what a model needs to choose pages. */
49
+ export declare function toSearchResult(query: string, response: ApiResponse): SearchResult;
50
+ type ModelOutput = {
51
+ type: "json";
52
+ value: {
53
+ [key: string]: string | number | undefined;
54
+ };
55
+ } | {
56
+ type: "content";
57
+ value: Array<{
58
+ type: "text";
59
+ text: string;
60
+ } | {
61
+ type: "file";
62
+ mediaType: string;
63
+ data: {
64
+ type: "data";
65
+ data: string;
66
+ };
67
+ }>;
68
+ };
69
+ /**
70
+ * Sends a screenshot to the model as an image part instead of a base64 string
71
+ * inside JSON, which would cost hundreds of thousands of text tokens.
72
+ */
73
+ export declare function toPageModelOutput(output: PageResult): ModelOutput;
74
+ export {};
75
+ //# sourceMappingURL=results.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"results.d.ts","sourceRoot":"","sources":["../src/results.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,YAAY,CAAC;AAE5D,qDAAqD;AACrD,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,iCAAiC;AACjC,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,6EAA6E;IAC7E,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,UAAU,WAAW;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;CACf;AAgBD;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,SAAS,UAAU,EAAE,EAC9B,QAAQ,EAAE,WAAW,GACpB,UAAU,CAmBZ;AAED,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,YAAY,CAoBjF;AAED,KAAK,WAAW,GACZ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,CAAA;CAAE,GACvE;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,KAAK,CACR;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAC9B;QACE,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;KACtC,CACJ,CAAC;CACH,CAAC;AAEN;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,CAcjE"}
@@ -0,0 +1,83 @@
1
+ function record(value) {
2
+ return value !== null && typeof value === "object" && !Array.isArray(value)
3
+ ? value
4
+ : {};
5
+ }
6
+ function text(value) {
7
+ return typeof value === "string" && value.length > 0 ? value : undefined;
8
+ }
9
+ function number(value) {
10
+ return typeof value === "number" && Number.isFinite(value) ? value : undefined;
11
+ }
12
+ /**
13
+ * Keeps the requested formats the API returned, plus usage and errors.
14
+ *
15
+ * When only HTML is requested, the API proxies the page and answers with the
16
+ * raw HTML string instead of a JSON object; that string is the html format.
17
+ */
18
+ export function toPageResult(url, formats, response) {
19
+ const result = { url, statusCode: response.status_code };
20
+ if (typeof response.data === "string") {
21
+ const html = text(response.data);
22
+ if (html !== undefined && formats.includes("html"))
23
+ result.html = html;
24
+ return result;
25
+ }
26
+ const data = record(response.data);
27
+ for (const format of formats) {
28
+ const content = text(data[format]);
29
+ if (content !== undefined)
30
+ result[format] = content;
31
+ }
32
+ const tokenUsage = number(data.token_usage);
33
+ if (tokenUsage !== undefined)
34
+ result.tokenUsage = tokenUsage;
35
+ const error = data.error;
36
+ if (error !== null && error !== undefined && error !== "") {
37
+ result.error = typeof error === "string" ? error : JSON.stringify(error);
38
+ }
39
+ return result;
40
+ }
41
+ /** Reduces the parsed search response to what a model needs to choose pages. */
42
+ export function toSearchResult(query, response) {
43
+ const body = record(record(response.data).data);
44
+ const organic = Array.isArray(body.organic) ? body.organic : [];
45
+ const peopleAlsoAsk = Array.isArray(body.people_also_ask) ? body.people_also_ask : [];
46
+ const nextPage = number(record(body.pagination).next_page);
47
+ return {
48
+ query: text(record(body.general).query) ?? query,
49
+ results: organic.map((entry) => {
50
+ const item = record(entry);
51
+ return {
52
+ rank: number(item.rank),
53
+ title: text(item.title),
54
+ link: text(item.link),
55
+ description: text(item.description),
56
+ source: text(item.source),
57
+ };
58
+ }),
59
+ ...(peopleAlsoAsk.length > 0 ? { peopleAlsoAsk } : {}),
60
+ nextPage: nextPage ?? null,
61
+ };
62
+ }
63
+ /**
64
+ * Sends a screenshot to the model as an image part instead of a base64 string
65
+ * inside JSON, which would cost hundreds of thousands of text tokens.
66
+ */
67
+ export function toPageModelOutput(output) {
68
+ const { screenshot, ...rest } = output;
69
+ if (screenshot === undefined)
70
+ return { type: "json", value: { ...rest } };
71
+ return {
72
+ type: "content",
73
+ value: [
74
+ { type: "text", text: JSON.stringify(rest) },
75
+ {
76
+ type: "file",
77
+ mediaType: "image",
78
+ data: { type: "data", data: screenshot },
79
+ },
80
+ ],
81
+ };
82
+ }
83
+ //# sourceMappingURL=results.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"results.js","sourceRoot":"","sources":["../src/results.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,60 @@
1
1
  {
2
2
  "name": "@mrscraper/ai-sdk",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "MrScraper tools for the Vercel AI SDK: retrieve public web pages as Markdown, HTML, or screenshots, search the web, and check account usage.",
5
+ "license": "MIT",
6
+ "author": "MrScraper <support@mrscraper.com> (https://mrscraper.com)",
7
+ "homepage": "https://docs.mrscraper.com/docs/integrations/vercel-ai-sdk",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/mrscraper-com/mrscraper-ai-sdk.git"
11
+ },
12
+ "bugs": {
13
+ "url": "https://github.com/mrscraper-com/mrscraper-ai-sdk/issues"
14
+ },
15
+ "keywords": [
16
+ "ai",
17
+ "ai-sdk",
18
+ "vercel",
19
+ "tools",
20
+ "web-scraping",
21
+ "web-search",
22
+ "mrscraper"
23
+ ],
24
+ "type": "module",
25
+ "main": "./dist/index.js",
26
+ "types": "./dist/index.d.ts",
27
+ "exports": {
28
+ ".": {
29
+ "types": "./dist/index.d.ts",
30
+ "import": "./dist/index.js"
31
+ }
32
+ },
33
+ "files": [
34
+ "dist"
35
+ ],
36
+ "sideEffects": false,
37
+ "engines": {
38
+ "node": ">=18"
39
+ },
40
+ "scripts": {
41
+ "build": "rm -rf dist && tsc -p tsconfig.build.json",
42
+ "typecheck": "tsc --noEmit",
43
+ "test": "vitest run",
44
+ "prepublishOnly": "npm run typecheck && npm test && npm run build"
45
+ },
46
+ "dependencies": {
47
+ "@mrscraper/sdk": "^3.1.0"
48
+ },
49
+ "peerDependencies": {
50
+ "ai": "^7.0.0",
51
+ "zod": "^3.25.76 || ^4.1.8"
52
+ },
53
+ "devDependencies": {
54
+ "@types/node": "^22.0.0",
55
+ "ai": "^7.0.148",
56
+ "typescript": "^5.9.0",
57
+ "vitest": "^3.2.0",
58
+ "zod": "^4.1.8"
59
+ }
60
+ }