@antonvishal/browserbase-tracking

Early-stage, community-maintained software. Not affiliated with or endorsed by Browserbase.

Small runtime package that transparently records Browserbase Search and Fetch calls using a caller-provided Drizzle PostgreSQL client.

Requires Node.js 22+ or Bun 1.2+. The package is ESM-only.

bun add @antonvishal/browserbase-tracking @browserbasehq/sdk drizzle-orm@rc

The adapter currently targets the Drizzle ORM 1.0 release-candidate API. The unqualified npm latest tag still points to Drizzle 0.x, so install the rc tag explicitly as shown above.

The supported Browserbase SDK range is the tested 2.16.x line. New SDK minor versions are adopted deliberately because tracking observes the SDK's APIPromise consumption methods while preserving the original promise object.

import Browserbase from "@browserbasehq/sdk";
import { flushTracking, withTracking } from "@antonvishal/browserbase-tracking";
import { drizzleAdapter } from "@antonvishal/browserbase-tracking/drizzle";
import { db } from "./db";

const adapter = drizzleAdapter(db);

const bb = withTracking({
  client: new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! }),
  adapter,
});

await bb.search.web({ query: "Browserbase pricing" });
await flushTracking(bb); // Wait for pending tracking writes before a short-lived process exits.

The PostgreSQL-only integration point is drizzleAdapter. It accepts the application's existing Drizzle PostgreSQL client; application schema files do not import tracking tables from this package.

browserbase_search_calls and browserbase_fetch_calls are the physical owner tables. browserbase_calls is a read-only UNION ALL view used by dashboards and analytics; it is not a third copy of tracked data. browserbase_tracking_metadata exposes the schema version expected by both writers and readers.

Request and response fields follow the Browserbase SDK Search and Fetch contracts and are stored once in normalized columns. The read view reconstructs SDK-shaped request and response JSON for inspection. Derived analytics fields such as result hosts, result count, content bytes, and effective Fetch billing mode remain materialized intentionally.

The schema deliberately avoids database checks for SDK behavior. PostgreSQL enforces identity, nullability, physical types, and uniqueness; the tracking writer normalizes outcomes, response shapes, timestamps, and derived metrics. This prevents best-effort observability writes from becoming coupled to evolving SDK response semantics.

The database owner must declare the documented schema as normal Drizzle tables and views, generate and apply its own migrations, and provision that schema before calls are tracked. The package ships a complete, copyable Drizzle definition at examples/schema.ts; it imports only from Drizzle and can be copied into an application's schema. Generate and review a migration from that application-owned definition. The adapter attempts inserts directly and never creates, validates, alters, migrates, or deletes database objects. Missing or incompatible schema errors are logged as best-effort tracking failures and never replace the Browserbase SDK result.

Only search.web and fetchAPI.create are tracked. Original SDK promises, raw responses, errors, retries, and all other resources are preserved. Writes are asynchronous and best-effort. flushTracking() waits until every Tracked Call started through that client has attempted persistence; write failures remain logged and do not replace SDK results. Request headers and API keys are never persisted.

Wrap each Browserbase client once. withTracking() rejects both an already tracked proxy and its original client so a logical SDK call cannot acquire duplicate tracking observers accidentally.

Data and privacy

Tracking stores Search queries and results, Fetch URLs and returned content, target response headers, transport response headers, and normalized error details. Those fields can contain personal, confidential, copyrighted, or security-sensitive data. Operators are responsible for access control, retention, redaction, and deletion policies for their database. Do not enable tracking where storing full request or response content would violate policy.

This package does not send tracking data to a separate service; it writes only through the adapter supplied by the application. The default Drizzle adapter does not create or migrate database objects.

withTracking depends only on the BrowserbaseTrackingAdapter interface. The application owns database provisioning and migrations. The local dashboard and its operational configuration belong to @antonvishal/browserbase-tracking-kit.

License

MIT. Browserbase is a trademark of its respective owner; use of the name here only describes compatibility.