@synoppy/ai-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saanora
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @synoppy/ai-sdk
+
+[![npm](https://img.shields.io/npm/v/@synoppy/ai-sdk.svg)](https://www.npmjs.com/package/@synoppy/ai-sdk) [![license](https://img.shields.io/npm/l/@synoppy/ai-sdk.svg)](./LICENSE)
+
+**Give your AI SDK agent the whole web.** [Synoppy](https://synoppy.com) tools for the [Vercel AI SDK](https://ai-sdk.dev) — drop them into `generateText` / `streamText` and your agent can read, search, crawl, map, extract, classify, enrich, screenshot, and pull images from the live web, all on one key.
+
+[**Get a free key →**](https://synoppy.com/dashboard) · [Docs](https://synoppy.com/docs) · [synoppy.com](https://synoppy.com)
+
+## Install
+
+```bash
+npm install @synoppy/ai-sdk ai zod
+```
+
+`ai` (v5+) and `zod` are peer dependencies — you almost certainly already have `ai`.
+
+## Quickstart
+
+```ts
+import { generateText } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { synoppyTools } from "@synoppy/ai-sdk";
+
+const { text } = await generateText({
+  model: openai("gpt-4o"),
+  tools: synoppyTools({ apiKey: process.env.SYNOPPY_API_KEY! }),
+  maxSteps: 5,
+  prompt: "Find the top HN story right now, read it, and summarize it in 3 bullets.",
+});
+
+console.log(text);
+```
+
+`synoppyTools()` returns an object keyed by tool name, so you can spread it straight into `tools`. Want just a few? Destructure them:
+
+```ts
+const { synoppy_read, synoppy_search } = synoppyTools({ apiKey });
+const tools = { synoppy_read, synoppy_search };
+```
+
+## Tools
+
+| Tool | Endpoint | What it does |
+| --- | --- | --- |
+| `synoppy_read` | `/api/scrape` | URL → clean markdown (nav/ads stripped) |
+| `synoppy_search` | `/api/search` | Ranked live-web results, optionally read to markdown |
+| `synoppy_crawl` | `/api/crawl` | Crawl a site → markdown per page (RAG ingest) |
+| `synoppy_map` | `/api/map` | Every URL on a domain |
+| `synoppy_extract` | `/api/extract` | Page → structured JSON from a prompt |
+| `synoppy_classify` | `/api/classify` | NAICS/SIC industry codes, or custom labels |
+| `synoppy_enrich` | `/api/brand` | Domain / email → brand profile (logo, colors, fonts, socials) |
+| `synoppy_images` | `/api/images` | Every image on a page + alt text |
+| `synoppy_screenshot` | `/api/screenshot` | URL → PNG (base64 data URL) for vision models |
+
+Each tool returns a lean, agent-friendly result plus `creditsUsed`. Failures come back as `{ error, code }` so the model can read them and recover instead of throwing.
+
+## Configuration
+
+`synoppyTools(options)` takes the same options as the [`@synoppy/sdk`](https://www.npmjs.com/package/@synoppy/sdk) client:
+
+```ts
+synoppyTools({
+  apiKey: process.env.SYNOPPY_API_KEY!, // required
+  baseUrl: "https://synoppy.com",       // optional override
+});
+```
+
+Need typed extraction (a JSON Schema), custom timeouts, or the raw responses? Use [`@synoppy/sdk`](https://www.npmjs.com/package/@synoppy/sdk) directly — it's re-exported here as `Synoppy`.
+
+MIT licensed · built by [Saanora](https://synoppy.com)

package/dist/index.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @synoppy/ai-sdk — Synoppy tools for the Vercel AI SDK.
+ *
+ * `synoppyTools({ apiKey })` returns the nine Synoppy endpoints as AI SDK tools,
+ * ready to spread into `generateText` / `streamText`. Each tool wraps the
+ * official `@synoppy/sdk` client and returns a lean, agent-friendly result;
+ * failures come back as `{ error, code }` so the model can read them and recover.
+ */
+import { type SynoppyOptions } from "@synoppy/sdk";
+export type SynoppyToolsOptions = SynoppyOptions;
+/**
+ * Build the full set of Synoppy AI SDK tools.
+ *
+ * @example
+ * ```ts
+ * import { generateText } from "ai";
+ * import { openai } from "@ai-sdk/openai";
+ * import { synoppyTools } from "@synoppy/ai-sdk";
+ *
+ * const { text } = await generateText({
+ *   model: openai("gpt-4o"),
+ *   tools: synoppyTools({ apiKey: process.env.SYNOPPY_API_KEY! }),
+ *   maxSteps: 5,
+ *   prompt: "Summarize the latest post on https://stripe.com/blog",
+ * });
+ * ```
+ */
+export declare function synoppyTools(options: SynoppyToolsOptions): {
+    synoppy_read: import("ai").Tool<{
+        url: string;
+        onlyMainContent?: boolean | undefined;
+        render?: boolean | undefined;
+    }, {
+        error: string;
+        code: string;
+    } | {
+        markdown: string | undefined;
+        metadata: import("@synoppy/sdk").ScrapeMetadata;
+        creditsUsed: number;
+    }>;
+    synoppy_search: import("ai").Tool<{
+        query: string;
+        markdown?: boolean | undefined;
+        maxResults?: number | undefined;
+        includeDomains?: string[] | undefined;
+        excludeDomains?: string[] | undefined;
+    }, {
+        error: string;
+        code: string;
+    } | {
+        results: import("@synoppy/sdk").SearchResult[];
+        creditsUsed: number;
+    }>;
+    synoppy_crawl: import("ai").Tool<{
+        url: string;
+        limit?: number | undefined;
+    }, {
+        error: string;
+        code: string;
+    } | {
+        domain: string;
+        discovered: number;
+        count: number;
+        pages: import("@synoppy/sdk").CrawlPage[];
+        creditsUsed: number;
+    }>;
+    synoppy_map: import("ai").Tool<{
+        url: string;
+    }, {
+        error: string;
+        code: string;
+    } | {
+        domain: string;
+        urls: string[];
+        count: number;
+        creditsUsed: number;
+    }>;
+    synoppy_extract: import("ai").Tool<{
+        url: string;
+        prompt?: string | undefined;
+    }, {
+        error: string;
+        code: string;
+    } | {
+        data: Record<string, unknown>;
+        creditsUsed: number;
+    }>;
+    synoppy_classify: import("ai").Tool<{
+        url: string;
+        labels?: string[] | undefined;
+    }, {
+        error: string;
+        code: string;
+    } | {
+        data: import("@synoppy/sdk").ClassifyIndustryData | import("@synoppy/sdk").ClassifyLabelData;
+        creditsUsed: number;
+    }>;
+    synoppy_enrich: import("ai").Tool<{
+        input: string;
+    }, {
+        error: string;
+        code: string;
+    } | {
+        name: string;
+        domain: string;
+        description: string | null;
+        logo: string | null;
+        colors: string[];
+        fonts: string[];
+        socials: import("@synoppy/sdk").Social[];
+        creditsUsed: number;
+    }>;
+    synoppy_images: import("ai").Tool<{
+        url: string;
+    }, {
+        error: string;
+        code: string;
+    } | {
+        images: import("@synoppy/sdk").ImageItem[];
+        count: number;
+        creditsUsed: number;
+    }>;
+    synoppy_screenshot: import("ai").Tool<{
+        url: string;
+        fullPage?: boolean | undefined;
+    }, {
+        error: string;
+        code: string;
+    } | {
+        screenshot: string;
+        sourceUrl: string;
+        creditsUsed: number;
+    }>;
+};
+export default synoppyTools;
+export { Synoppy, SynoppyError } from "@synoppy/sdk";
+export type { SynoppyOptions } from "@synoppy/sdk";

package/dist/index.js

@@ -0,0 +1,149 @@
+/**
+ * @synoppy/ai-sdk — Synoppy tools for the Vercel AI SDK.
+ *
+ * `synoppyTools({ apiKey })` returns the nine Synoppy endpoints as AI SDK tools,
+ * ready to spread into `generateText` / `streamText`. Each tool wraps the
+ * official `@synoppy/sdk` client and returns a lean, agent-friendly result;
+ * failures come back as `{ error, code }` so the model can read them and recover.
+ */
+import { tool } from "ai";
+import { z } from "zod";
+import { Synoppy, SynoppyError } from "@synoppy/sdk";
+/** Run an SDK call, returning an agent-readable error object instead of throwing. */
+async function guard(fn) {
+    try {
+        return await fn();
+    }
+    catch (e) {
+        if (e instanceof SynoppyError)
+            return { error: e.message, code: e.code };
+        return { error: e instanceof Error ? e.message : "Unknown error", code: "ERROR" };
+    }
+}
+/**
+ * Build the full set of Synoppy AI SDK tools.
+ *
+ * @example
+ * ```ts
+ * import { generateText } from "ai";
+ * import { openai } from "@ai-sdk/openai";
+ * import { synoppyTools } from "@synoppy/ai-sdk";
+ *
+ * const { text } = await generateText({
+ *   model: openai("gpt-4o"),
+ *   tools: synoppyTools({ apiKey: process.env.SYNOPPY_API_KEY! }),
+ *   maxSteps: 5,
+ *   prompt: "Summarize the latest post on https://stripe.com/blog",
+ * });
+ * ```
+ */
+export function synoppyTools(options) {
+    const client = new Synoppy(options);
+    return {
+        synoppy_read: tool({
+            description: "Read any URL and return it as clean, LLM-ready markdown (navigation, ads, and boilerplate stripped). Use to fetch the content of a specific web page.",
+            inputSchema: z.object({
+                url: z.string().describe("The absolute URL to read, e.g. https://example.com/blog/post"),
+                onlyMainContent: z.boolean().optional().describe("Strip navigation, headers, footers, and ads (default true)."),
+                render: z.boolean().optional().describe("Render JS-heavy / single-page apps in a real browser before reading (default false)."),
+            }),
+            execute: ({ url, onlyMainContent, render }) => guard(async () => {
+                const r = await client.read(url, { onlyMainContent, render });
+                return { markdown: r.markdown, metadata: r.metadata, creditsUsed: r.creditsUsed };
+            }),
+        }),
+        synoppy_search: tool({
+            description: "Search the live web and get back ranked results with clean source URLs. Use for current information, research, or to find pages before reading them. Set markdown to also read each result into clean markdown in the same call.",
+            inputSchema: z.object({
+                query: z.string().describe("The search query."),
+                maxResults: z.number().int().min(1).max(15).optional().describe("How many results to return (default 5)."),
+                markdown: z.boolean().optional().describe("Also read each result into clean markdown."),
+                includeDomains: z.array(z.string()).optional().describe("Only return results from these domains."),
+                excludeDomains: z.array(z.string()).optional().describe("Never return results from these domains."),
+            }),
+            execute: ({ query, ...opts }) => guard(async () => {
+                const r = await client.search(query, opts);
+                return { results: r.results, creditsUsed: r.creditsUsed };
+            }),
+        }),
+        synoppy_crawl: tool({
+            description: "Crawl a website from a starting URL and return clean markdown for every page found. Use to ingest a whole site or docs section (e.g. to build a RAG corpus).",
+            inputSchema: z.object({
+                url: z.string().describe("The starting URL."),
+                limit: z.number().int().min(1).max(25).optional().describe("Maximum pages to crawl (default 10)."),
+            }),
+            execute: ({ url, limit }) => guard(async () => {
+                const r = await client.crawl(url, { limit });
+                return { domain: r.domain, discovered: r.discovered, count: r.count, pages: r.pages, creditsUsed: r.creditsUsed };
+            }),
+        }),
+        synoppy_map: tool({
+            description: "Discover every URL on a domain in one call (from sitemaps and links). Use to understand a site's structure before crawling or reading specific pages.",
+            inputSchema: z.object({ url: z.string().describe("The domain or URL to map, e.g. https://stripe.com") }),
+            execute: ({ url }) => guard(async () => {
+                const r = await client.map(url);
+                return { domain: r.domain, urls: r.urls, count: r.count, creditsUsed: r.creditsUsed };
+            }),
+        }),
+        synoppy_extract: tool({
+            description: "Extract structured JSON from a page using AI. Describe the fields you want in a natural-language prompt and get back typed data (pricing tables, product specs, job listings, etc.).",
+            inputSchema: z.object({
+                url: z.string().describe("The page to extract from."),
+                prompt: z.string().optional().describe("Describe the JSON you want, e.g. 'the pricing tiers as a list of name + price'."),
+            }),
+            execute: ({ url, prompt }) => guard(async () => {
+                const r = await client.extract(url, { prompt });
+                return { data: r.data, creditsUsed: r.creditsUsed };
+            }),
+        }),
+        synoppy_classify: tool({
+            description: "Classify a company by its website — NAICS/SIC industry codes by default, or scored against your own custom labels.",
+            inputSchema: z.object({
+                url: z.string().describe("The company website."),
+                labels: z.array(z.string()).optional().describe("Custom labels to score against instead of industry codes."),
+            }),
+            execute: ({ url, labels }) => guard(async () => {
+                const r = await client.classify(url, { labels });
+                return { data: r.data, creditsUsed: r.creditsUsed };
+            }),
+        }),
+        synoppy_enrich: tool({
+            description: "Resolve a domain, URL, or work email into a live brand profile: name, logo, colors, fonts, socials, and description — read straight from the site.",
+            inputSchema: z.object({ input: z.string().describe("A domain, URL, or work email, e.g. stripe.com or jane@stripe.com") }),
+            execute: ({ input }) => guard(async () => {
+                const r = await client.enrich(input);
+                return {
+                    name: r.name,
+                    domain: r.domain,
+                    description: r.description,
+                    logo: r.logo,
+                    colors: r.colors,
+                    fonts: r.fonts,
+                    socials: r.socials,
+                    creditsUsed: r.creditsUsed,
+                };
+            }),
+        }),
+        synoppy_images: tool({
+            description: "Collect every image on a page with its alt text and dimensions.",
+            inputSchema: z.object({ url: z.string().describe("The page to collect images from.") }),
+            execute: ({ url }) => guard(async () => {
+                const r = await client.images(url);
+                return { images: r.images, count: r.count, creditsUsed: r.creditsUsed };
+            }),
+        }),
+        synoppy_screenshot: tool({
+            description: "Capture a URL as a PNG screenshot, returned as a base64 data URL — so a vision model can see the page, or to snapshot a layout. Note: the returned image is large.",
+            inputSchema: z.object({
+                url: z.string().describe("The page to capture."),
+                fullPage: z.boolean().optional().describe("Capture the entire scrollable page instead of just the viewport (default false)."),
+            }),
+            execute: ({ url, fullPage }) => guard(async () => {
+                const r = await client.screenshot(url, { fullPage });
+                return { screenshot: r.screenshot, sourceUrl: r.sourceUrl, creditsUsed: r.creditsUsed };
+            }),
+        }),
+    };
+}
+export default synoppyTools;
+export { Synoppy, SynoppyError } from "@synoppy/sdk";

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@synoppy/ai-sdk",
+  "version": "1.0.0",
+  "description": "Vercel AI SDK tools for Synoppy — give your agent the whole web: read, search, crawl, map, extract, classify, enrich, images, and screenshot on one key.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["synoppy", "ai-sdk", "vercel-ai", "tools", "agents", "web-scraping", "web-search", "rag", "llm", "markdown"],
+  "author": "Saanora <support@synoppy.com>",
+  "homepage": "https://synoppy.com/docs",
+  "repository": { "type": "git", "url": "git+https://github.com/Synoppy/synoppy-ai-sdk.git" },
+  "bugs": { "url": "https://github.com/Synoppy/synoppy-ai-sdk/issues" },
+  "dependencies": {
+    "@synoppy/sdk": "^1.1.1"
+  },
+  "peerDependencies": {
+    "ai": ">=5.0.0",
+    "zod": ">=3.23.0"
+  },
+  "devDependencies": {
+    "ai": "^5.0.0",
+    "typescript": "^5.5.0",
+    "zod": "^3.23.8"
+  }
+}