@sholajegede/bright-data-sync 0.1.1-alpha.0

package/dist/component/lib.js

@@ -0,0 +1,314 @@
+import { v } from "convex/values";
+import { action, internalMutation, internalQuery, query, } from "./_generated/server.js";
+import { internal } from "./_generated/api.js";
+// ─── Constants ───────────────────────────────────────────────────────────────
+const DEFAULT_SEARCH_TTL_MS = 1000 * 60 * 60; // 1 hour
+const DEFAULT_PAGE_TTL_MS = 1000 * 60 * 60 * 6; // 6 hours
+// ─── Internal helpers ────────────────────────────────────────────────────────
+export const getSearchByQuery = internalQuery({
+    args: { query: v.string() },
+    returns: v.union(v.null(), v.object({
+        _id: v.id("searches"),
+        _creationTime: v.number(),
+        query: v.string(),
+        vertical: v.optional(v.string()),
+        recency: v.optional(v.string()),
+        results: v.string(),
+        fetchedAt: v.number(),
+        expiresAt: v.number(),
+    })),
+    handler: async (ctx, args) => {
+        return await ctx.db
+            .query("searches")
+            .withIndex("by_query", (q) => q.eq("query", args.query))
+            .first();
+    },
+});
+export const getPageByUrl = internalQuery({
+    args: { url: v.string() },
+    returns: v.union(v.null(), v.object({
+        _id: v.id("pages"),
+        _creationTime: v.number(),
+        url: v.string(),
+        content: v.string(),
+        fetchedAt: v.number(),
+        expiresAt: v.number(),
+    })),
+    handler: async (ctx, args) => {
+        return await ctx.db
+            .query("pages")
+            .withIndex("by_url", (q) => q.eq("url", args.url))
+            .first();
+    },
+});
+export const upsertSearch = internalMutation({
+    args: {
+        query: v.string(),
+        vertical: v.optional(v.string()),
+        recency: v.optional(v.string()),
+        results: v.string(),
+        ttlMs: v.optional(v.number()),
+    },
+    returns: v.id("searches"),
+    handler: async (ctx, args) => {
+        const now = Date.now();
+        const expiresAt = now + (args.ttlMs ?? DEFAULT_SEARCH_TTL_MS);
+        const existing = await ctx.db
+            .query("searches")
+            .withIndex("by_query", (q) => q.eq("query", args.query))
+            .first();
+        if (existing) {
+            await ctx.db.patch("searches", existing._id, {
+                results: args.results,
+                fetchedAt: now,
+                expiresAt,
+                vertical: args.vertical,
+                recency: args.recency,
+            });
+            return existing._id;
+        }
+        return await ctx.db.insert("searches", {
+            query: args.query,
+            vertical: args.vertical,
+            recency: args.recency,
+            results: args.results,
+            fetchedAt: now,
+            expiresAt,
+        });
+    },
+});
+export const upsertPage = internalMutation({
+    args: {
+        url: v.string(),
+        content: v.string(),
+        ttlMs: v.optional(v.number()),
+    },
+    returns: v.id("pages"),
+    handler: async (ctx, args) => {
+        const now = Date.now();
+        const expiresAt = now + (args.ttlMs ?? DEFAULT_PAGE_TTL_MS);
+        const existing = await ctx.db
+            .query("pages")
+            .withIndex("by_url", (q) => q.eq("url", args.url))
+            .first();
+        if (existing) {
+            await ctx.db.patch("pages", existing._id, {
+                content: args.content,
+                fetchedAt: now,
+                expiresAt,
+            });
+            return existing._id;
+        }
+        return await ctx.db.insert("pages", {
+            url: args.url,
+            content: args.content,
+            fetchedAt: now,
+            expiresAt,
+        });
+    },
+});
+export const deleteSearchByQuery = internalMutation({
+    args: { query: v.string() },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const existing = await ctx.db
+            .query("searches")
+            .withIndex("by_query", (q) => q.eq("query", args.query))
+            .first();
+        if (existing)
+            await ctx.db.delete("searches", existing._id);
+        return null;
+    },
+});
+export const deletePageByUrl = internalMutation({
+    args: { url: v.string() },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const existing = await ctx.db
+            .query("pages")
+            .withIndex("by_url", (q) => q.eq("url", args.url))
+            .first();
+        if (existing)
+            await ctx.db.delete("pages", existing._id);
+        return null;
+    },
+});
+// ─── Public queries (reactive) ───────────────────────────────────────────────
+export const getSearch = query({
+    args: { query: v.string() },
+    returns: v.union(v.null(), v.object({
+        results: v.string(),
+        fetchedAt: v.number(),
+        expiresAt: v.number(),
+        isFresh: v.boolean(),
+    })),
+    handler: async (ctx, args) => {
+        const row = await ctx.db
+            .query("searches")
+            .withIndex("by_query", (q) => q.eq("query", args.query))
+            .first();
+        if (!row)
+            return null;
+        return {
+            results: row.results,
+            fetchedAt: row.fetchedAt,
+            expiresAt: row.expiresAt,
+            isFresh: Date.now() < row.expiresAt,
+        };
+    },
+});
+export const getPage = query({
+    args: { url: v.string() },
+    returns: v.union(v.null(), v.object({
+        content: v.string(),
+        fetchedAt: v.number(),
+        expiresAt: v.number(),
+        isFresh: v.boolean(),
+    })),
+    handler: async (ctx, args) => {
+        const row = await ctx.db
+            .query("pages")
+            .withIndex("by_url", (q) => q.eq("url", args.url))
+            .first();
+        if (!row)
+            return null;
+        return {
+            content: row.content,
+            fetchedAt: row.fetchedAt,
+            expiresAt: row.expiresAt,
+            isFresh: Date.now() < row.expiresAt,
+        };
+    },
+});
+// ─── Public actions ──────────────────────────────────────────────────────────
+export const search = action({
+    args: {
+        query: v.string(),
+        vertical: v.optional(v.string()),
+        recency: v.optional(v.string()),
+        ttlMs: v.optional(v.number()),
+        // Passed in from client wrapper — never stored
+        brightdataApiToken: v.string(),
+        brightdataSearchZone: v.optional(v.string()),
+    },
+    returns: v.object({
+        results: v.string(),
+        fromCache: v.boolean(),
+        fetchedAt: v.number(),
+    }),
+    handler: async (ctx, args) => {
+        // 1. Check cache
+        // 1. Check cache
+        const cached = (await ctx.runQuery(internal.lib.getSearchByQuery, {
+            query: args.query,
+        }));
+        if (cached && Date.now() < cached.expiresAt) {
+            return {
+                results: cached.results,
+                fromCache: true,
+                fetchedAt: cached.fetchedAt,
+            };
+        }
+        // 2. Fetch from Bright Data SERP API
+        const zone = args.brightdataSearchZone ?? "serp_api1";
+        const url = new URL("https://api.brightdata.com/request");
+        const body = {
+            zone,
+            url: `https://www.google.com/search?q=${encodeURIComponent(args.query)}${args.vertical ? `&tbm=${args.vertical}` : ""}${args.recency ? `&tbs=qdr:${args.recency}` : ""}`,
+            format: "json",
+        };
+        const response = await fetch(url.toString(), {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${args.brightdataApiToken}`,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            throw new Error(`Bright Data SERP API error: ${response.status} ${await response.text()}`);
+        }
+        const results = await response.text();
+        const now = Date.now();
+        // 3. Store in cache
+        await ctx.runMutation(internal.lib.upsertSearch, {
+            query: args.query,
+            vertical: args.vertical,
+            recency: args.recency,
+            results,
+            ttlMs: args.ttlMs,
+        });
+        return { results, fromCache: false, fetchedAt: now };
+    },
+});
+export const scrape = action({
+    args: {
+        url: v.string(),
+        ttlMs: v.optional(v.number()),
+        brightdataApiToken: v.string(),
+        brightdataWebUnlockerZone: v.optional(v.string()),
+    },
+    returns: v.object({
+        content: v.string(),
+        fromCache: v.boolean(),
+        fetchedAt: v.number(),
+    }),
+    handler: async (ctx, args) => {
+        // 1. Check cache
+        const cached = (await ctx.runQuery(internal.lib.getPageByUrl, {
+            url: args.url,
+        }));
+        if (cached && Date.now() < cached.expiresAt) {
+            return {
+                content: cached.content,
+                fromCache: true,
+                fetchedAt: cached.fetchedAt,
+            };
+        }
+        // 2. Fetch from Bright Data Web Unlocker
+        const zone = args.brightdataWebUnlockerZone ?? "web_unlocker1";
+        const response = await fetch("https://api.brightdata.com/request", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${args.brightdataApiToken}`,
+            },
+            body: JSON.stringify({
+                zone,
+                url: args.url,
+                format: "raw",
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`Bright Data Web Unlocker error: ${response.status} ${await response.text()}`);
+        }
+        const content = await response.text();
+        const now = Date.now();
+        // 3. Store in cache
+        await ctx.runMutation(internal.lib.upsertPage, {
+            url: args.url,
+            content,
+            ttlMs: args.ttlMs,
+        });
+        return { content, fromCache: false, fetchedAt: now };
+    },
+});
+export const invalidate = action({
+    args: {
+        query: v.optional(v.string()),
+        url: v.optional(v.string()),
+    },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        if (args.query) {
+            await ctx.runMutation(internal.lib.deleteSearchByQuery, {
+                query: args.query,
+            });
+        }
+        if (args.url) {
+            await ctx.runMutation(internal.lib.deletePageByUrl, { url: args.url });
+        }
+        return null;
+    },
+});
+//# sourceMappingURL=lib.js.map

package/dist/component/lib.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../../src/component/lib.ts"],"names":[],"mappings":"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"}

package/dist/component/schema.d.ts

@@ -0,0 +1,47 @@
+declare const _default: import("convex/server").SchemaDefinition<{
+    searches: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        recency?: string | undefined;
+        vertical?: string | undefined;
+        query: string;
+        results: string;
+        fetchedAt: number;
+        expiresAt: number;
+    }, {
+        query: import("convex/values").VString<string, "required">;
+        vertical: import("convex/values").VString<string | undefined, "optional">;
+        recency: import("convex/values").VString<string | undefined, "optional">;
+        results: import("convex/values").VString<string, "required">;
+        fetchedAt: import("convex/values").VFloat64<number, "required">;
+        expiresAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "query" | "recency" | "vertical" | "results" | "fetchedAt" | "expiresAt">, {
+        by_query: ["query", "_creationTime"];
+        by_expires: ["expiresAt", "_creationTime"];
+    }, {}, {}>;
+    pages: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        url: string;
+        fetchedAt: number;
+        expiresAt: number;
+        content: string;
+    }, {
+        url: import("convex/values").VString<string, "required">;
+        content: import("convex/values").VString<string, "required">;
+        fetchedAt: import("convex/values").VFloat64<number, "required">;
+        expiresAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "url" | "fetchedAt" | "expiresAt" | "content">, {
+        by_url: ["url", "_creationTime"];
+        by_expires: ["expiresAt", "_creationTime"];
+    }, {}, {}>;
+    processedRequests: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        type: "search" | "scrape";
+        requestKey: string;
+        completedAt: number;
+    }, {
+        requestKey: import("convex/values").VString<string, "required">;
+        type: import("convex/values").VUnion<"search" | "scrape", [import("convex/values").VLiteral<"search", "required">, import("convex/values").VLiteral<"scrape", "required">], "required", never>;
+        completedAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "type" | "requestKey" | "completedAt">, {
+        by_key: ["requestKey", "_creationTime"];
+    }, {}, {}>;
+}, true>;
+export default _default;
+//# sourceMappingURL=schema.d.ts.map

package/dist/component/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGA,wBA0BG"}

package/dist/component/schema.js

@@ -0,0 +1,28 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+export default defineSchema({
+    searches: defineTable({
+        query: v.string(),
+        vertical: v.optional(v.string()), // "web" | "news" | "shopping" etc.
+        recency: v.optional(v.string()), // "d" | "w" | "m" etc.
+        results: v.string(), // JSON-stringified array of results
+        fetchedAt: v.number(), // Date.now()
+        expiresAt: v.number(), // fetchedAt + TTL
+    })
+        .index("by_query", ["query"])
+        .index("by_expires", ["expiresAt"]),
+    pages: defineTable({
+        url: v.string(),
+        content: v.string(), // markdown from Web Unlocker
+        fetchedAt: v.number(),
+        expiresAt: v.number(),
+    })
+        .index("by_url", ["url"])
+        .index("by_expires", ["expiresAt"]),
+    processedRequests: defineTable({
+        requestKey: v.string(), // hash of query+vertical+recency OR url
+        type: v.union(v.literal("search"), v.literal("scrape")),
+        completedAt: v.number(),
+    }).index("by_key", ["requestKey"]),
+});
+//# sourceMappingURL=schema.js.map

package/dist/component/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAElC,eAAe,YAAY,CAAC;IAC1B,QAAQ,EAAE,WAAW,CAAC;QACpB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;QACjB,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,mCAAmC;QACrE,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,EAAG,uBAAuB;QACzD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,EAAe,oCAAoC;QACtE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,EAAa,aAAa;QAC/C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,EAAa,kBAAkB;KACrD,CAAC;SACC,KAAK,CAAC,UAAU,EAAE,CAAC,OAAO,CAAC,CAAC;SAC5B,KAAK,CAAC,YAAY,EAAE,CAAC,WAAW,CAAC,CAAC;IAErC,KAAK,EAAE,WAAW,CAAC;QACjB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;QACf,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,EAAI,6BAA6B;QACpD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;KACtB,CAAC;SACC,KAAK,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC;SACxB,KAAK,CAAC,YAAY,EAAE,CAAC,WAAW,CAAC,CAAC;IAErC,iBAAiB,EAAE,WAAW,CAAC;QAC7B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,wCAAwC;QAChE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACvD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;KACxB,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,YAAY,CAAC,CAAC;CACnC,CAAC,CAAC"}

package/dist/react/index.d.ts

@@ -0,0 +1,2 @@
+export declare const useMyComponent: () => {};
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,cAAc,UAE1B,CAAC"}

package/dist/react/index.js

@@ -0,0 +1,6 @@
+"use client";
+// This is where React components / hooks go.
+export const useMyComponent = () => {
+    return {};
+};
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,6CAA6C;AAE7C,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,EAAE;IACjC,OAAO,EAAE,CAAC;AACZ,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@sholajegede/bright-data-sync",
+  "description": "A bright data sync component for Convex.",
+  "repository": "github:sholajegede/bright-data-sync",
+  "homepage": "https://github.com/sholajegede/bright-data-sync#readme",
+  "bugs": {
+    "url": "https://github.com/sholajegede/bright-data-sync/issues"
+  },
+  "version": "0.1.1-alpha.0",
+  "license": "Apache-2.0",
+  "keywords": [
+    "convex",
+    "component"
+  ],
+  "type": "module",
+  "scripts": {
+    "dev": "run-p -r 'dev:*'",
+    "dev:backend": "convex dev --typecheck-components",
+    "dev:frontend": "cd example && vite --clearScreen false",
+    "dev:build": "chokidar 'tsconfig*.json' 'src/**/*.ts' -i '**/*.test.ts' -c 'npm run build:codegen' --initial",
+    "predev": "path-exists .env.local dist || (npm run build && convex dev --once)",
+    "build": "tsc --project ./tsconfig.build.json",
+    "build:codegen": "npx convex codegen --component-dir ./src/component && npm run build",
+    "build:clean": "rm -rf dist *.tsbuildinfo && npm run build:codegen",
+    "typecheck": "tsc --noEmit && tsc -p example && tsc -p example/convex",
+    "lint": "eslint .",
+    "all": "run-p -r 'dev:*' 'test:watch'",
+    "test": "vitest run --typecheck",
+    "test:watch": "vitest --typecheck --clearScreen false",
+    "test:debug": "vitest --inspect-brk --no-file-parallelism",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text",
+    "preversion": "npm ci && npm run build:clean && run-p test lint typecheck",
+    "prepublishOnly": "npm whoami || npm login",
+    "alpha": "npm version prerelease --preid alpha && npm publish --tag alpha && git push --follow-tags",
+    "release": "npm version patch && npm publish && git push --follow-tags",
+    "version": "vim -c 'normal o' -c 'normal o## '$npm_package_version CHANGELOG.md && prettier -w CHANGELOG.md && git add CHANGELOG.md"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    },
+    "./test": "./src/test.ts",
+    "./_generated/component.js": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./_generated/component": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./convex.config.js": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    },
+    "./convex.config": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    }
+  },
+  "peerDependencies": {
+    "convex": "^1.32.0",
+    "react": "^18.3.1 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@convex-dev/eslint-plugin": "^1.1.1",
+    "@edge-runtime/vm": "^5.0.0",
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "9.39.4",
+    "@types/node": "^24.12.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.4",
+    "chokidar-cli": "3.0.0",
+    "convex": "1.32.0",
+    "convex-test": "0.0.41",
+    "eslint": "9.39.3",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.4.0",
+    "npm-run-all2": "8.0.4",
+    "path-exists-cli": "2.0.0",
+    "pkg-pr-new": "^0.0.65",
+    "prettier": "3.8.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.56.1",
+    "vite": "7.3.1",
+    "vitest": "4.0.18"
+  },
+  "types": "./dist/client/index.d.ts",
+  "module": "./dist/client/index.js"
+}

package/src/client/_generated/_ignore.ts

@@ -0,0 +1 @@
+// This is only here so convex-test can detect a _generated folder

package/src/client/index.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, test } from "vitest";
+import { BrightDataSync } from "./index.js";
+import { components } from "./setup.test.js";
+
+describe("BrightDataSync client", () => {
+  test("instantiates with required options", () => {
+    const client = new BrightDataSync(components.brightDataSync, {
+      BRIGHTDATA_API_TOKEN: "test-token",
+    });
+    expect(client).toBeDefined();
+    expect(client.component).toBeDefined();
+  });
+});

package/src/client/index.ts

@@ -0,0 +1,100 @@
+import type { GenericActionCtx, GenericDataModel } from "convex/server";
+import type { ComponentApi } from "../component/_generated/component.js";
+
+export type BrightDataSyncOptions = {
+  /** Your Bright Data API token */
+  BRIGHTDATA_API_TOKEN: string;
+  /** Bright Data SERP zone name (default: "serp_api1") */
+  BRIGHTDATA_SEARCH_ZONE?: string;
+  /** Bright Data Web Unlocker zone name (default: "web_unlocker1") */
+  BRIGHTDATA_WEB_UNLOCKER_ZONE?: string;
+  /** Default TTL for search results in ms (default: 1 hour) */
+  DEFAULT_SEARCH_TTL_MS?: number;
+  /** Default TTL for scraped pages in ms (default: 6 hours) */
+  DEFAULT_PAGE_TTL_MS?: number;
+};
+
+export type SearchArgs = {
+  query: string;
+  vertical?: string;
+  recency?: string;
+  ttlMs?: number;
+};
+
+export type ScrapeArgs = {
+  url: string;
+  ttlMs?: number;
+};
+
+/**
+ * Client wrapper for the BrightDataSync Convex component.
+ *
+ * @example
+ * ```ts
+ * // convex/brightData.ts
+ * import { components } from "./_generated/api.js";
+ * import { BrightDataSync } from "@sholajegede/bright-data-sync";
+ *
+ * export const brightData = new BrightDataSync(components.brightDataSync, {
+ *   BRIGHTDATA_API_TOKEN: process.env.BRIGHTDATA_API_TOKEN!,
+ * });
+ *
+ * // In an action:
+ * export const mySearch = action({
+ *   args: { q: v.string() },
+ *   handler: async (ctx, args) => {
+ *     return await brightData.search(ctx, { query: args.q });
+ *   },
+ * });
+ * ```
+ */
+export class BrightDataSync {
+  constructor(
+    public component: ComponentApi,
+    private options: BrightDataSyncOptions,
+  ) {}
+
+  /**
+   * Search via Bright Data SERP API. Returns cached results if fresh.
+   */
+  async search(ctx: ActionCtx, args: SearchArgs) {
+    return ctx.runAction(this.component.lib.search, {
+      query: args.query,
+      vertical: args.vertical,
+      recency: args.recency,
+      ttlMs: args.ttlMs ?? this.options.DEFAULT_SEARCH_TTL_MS,
+      brightdataApiToken: this.options.BRIGHTDATA_API_TOKEN,
+      brightdataSearchZone: this.options.BRIGHTDATA_SEARCH_ZONE,
+    });
+  }
+
+  /**
+   * Scrape a URL via Bright Data Web Unlocker. Returns cached content if fresh.
+   */
+  async scrape(ctx: ActionCtx, args: ScrapeArgs) {
+    return ctx.runAction(this.component.lib.scrape, {
+      url: args.url,
+      ttlMs: args.ttlMs ?? this.options.DEFAULT_PAGE_TTL_MS,
+      brightdataApiToken: this.options.BRIGHTDATA_API_TOKEN,
+      brightdataWebUnlockerZone: this.options.BRIGHTDATA_WEB_UNLOCKER_ZONE,
+    });
+  }
+
+  /**
+   * Invalidate cached search results or page content.
+   */
+  async invalidate(
+    ctx: ActionCtx,
+    args: { query?: string; url?: string },
+  ) {
+    return ctx.runAction(this.component.lib.invalidate, args);
+  }
+}
+
+// Re-export the component API type for convenience
+export type { ComponentApi };
+
+type ActionCtx = Pick<
+  GenericActionCtx<GenericDataModel>,
+  "runQuery" | "runMutation" | "runAction"
+>;