Add public API contract tests (browserbase#1290)

# why
We need to create stubs for the client sdk, and this allows us to write
tests so that we can confirm that our stub signatures have full parity.

# what changed
Added full contract tests which check just the public facing API *types*
https://vitest.dev/guide/testing-types

Also made it so that all types from `/public/types` are explicitly
re-exported through index.ts, so that we can have a single place to
review all public exports.

These tests might be a bit more in-depth then we ultimately want - we
are checking function signatures for stuff like the vercel AI client,
which might be more brittle than we want currently, but we will likely
be removing some of these public exports anyways with the canonical
work.

# test plan
You can run `pnpm --filter @browserbasehq/stagehand test:vitest`

Author: monadoid

.changeset/dark-pans-carry.md

@@ -2,4 +2,4 @@
 "@browserbasehq/stagehand": patch
 ---
 
-Add support for zod 4, while maintaining backwards compatibility for zod 3 
+Add support for zod 4, while maintaining backwards compatibility for zod 3

packages/core/lib/v3/index.ts

@@ -1,11 +1,45 @@
 export { V3 } from "./v3";
 export { V3 as Stagehand } from "./v3";
 
-// Re-export common V3 types for consumers
-export * from "./llm/LLMClient";
 export * from "./types/public";
-export * from "./agent/AgentProvider";
-export * from "../utils";
-export * from "./zodCompat";
+export { AnnotatedScreenshotText, LLMClient } from "./llm/LLMClient";
+
+export { AgentProvider, modelToAgentProviderMap } from "./agent/AgentProvider";
+
+export {
+  validateZodSchema,
+  isRunningInBun,
+  toGeminiSchema,
+  getZodType,
+  transformSchema,
+  injectUrls,
+  providerEnvVarMap,
+  loadApiKeyFromEnv,
+  trimTrailingTextNode,
+  jsonSchemaToZod,
+} from "../utils";
+export { isZod4Schema, isZod3Schema, toJsonSchema } from "./zodCompat";
+
 export { connectToMCPServer } from "./mcp/connection";
 export { V3Evaluator } from "../v3Evaluator";
+
+export type {
+  ChatMessage,
+  ChatMessageContent,
+  ChatMessageImageContent,
+  ChatMessageTextContent,
+  ChatCompletionOptions,
+  LLMResponse,
+  CreateChatCompletionOptions,
+  LLMUsage,
+  LLMParsedResponse,
+} from "./llm/LLMClient";
+
+export type {
+  StagehandZodSchema,
+  StagehandZodObject,
+  InferStagehandSchema,
+  JsonSchemaDocument,
+} from "./zodCompat";
+
+export type { JsonSchema, JsonSchemaProperty } from "../utils";

packages/core/package.json

@@ -19,7 +19,7 @@
     "e2e:bb": "playwright test --config=lib/v3/tests/v3.bb.playwright.config.ts",
     "lint": "cd ../.. && prettier --check packages/core && cd packages/core && eslint .",
     "format": "prettier --write .",
-    "test:vitest": "pnpm run build-js && vitest run --config vitest.config.ts"
+    "test:vitest": "pnpm run build-js && pnpm run typecheck && vitest run --config vitest.config.ts"
   },
   "files": [
     "dist/index.js",

packages/core/tests/public-api/export-surface.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+import StagehandDefaultExport, * as Stagehand from "../../dist/index.js";
+import { publicErrorTypes } from "./public-error-types.test";
+
+// Type matcher guidelines:
+//
+// toEqualTypeOf – Default. Assert full, deep type equality; any type change should fail.
+//   e.g. expectTypeOf<ReturnType<typeof foo>>().toEqualTypeOf<FooResult>()
+//
+// toMatchObjectType – Assert (part of) an object's shape while allowing extra fields.
+//   e.g. expectTypeOf(user).toMatchObjectType<{ id: string; email: string }>()
+//
+// toExtend – Assert that a type is compatible with a broader contract (assignable/extends).
+//   e.g. expectTypeOf<User>().toExtend<BaseUser>()
+
+const publicApiShape = {
+  AISdkClient: Stagehand.AISdkClient,
+  AVAILABLE_CUA_MODELS: Stagehand.AVAILABLE_CUA_MODELS,
+  AgentProvider: Stagehand.AgentProvider,
+  AnnotatedScreenshotText: Stagehand.AnnotatedScreenshotText,
+  ConsoleMessage: Stagehand.ConsoleMessage,
+  LLMClient: Stagehand.LLMClient,
+  LOG_LEVEL_NAMES: Stagehand.LOG_LEVEL_NAMES,
+  Response: Stagehand.Response,
+  Stagehand: Stagehand.Stagehand,
+  V3: Stagehand.V3,
+  V3Evaluator: Stagehand.V3Evaluator,
+  V3FunctionName: Stagehand.V3FunctionName,
+  connectToMCPServer: Stagehand.connectToMCPServer,
+  default: StagehandDefaultExport,
+  defaultExtractSchema: Stagehand.defaultExtractSchema,
+  getZodType: Stagehand.getZodType,
+  injectUrls: Stagehand.injectUrls,
+  isRunningInBun: Stagehand.isRunningInBun,
+  isZod3Schema: Stagehand.isZod3Schema,
+  isZod4Schema: Stagehand.isZod4Schema,
+  jsonSchemaToZod: Stagehand.jsonSchemaToZod,
+  loadApiKeyFromEnv: Stagehand.loadApiKeyFromEnv,
+  modelToAgentProviderMap: Stagehand.modelToAgentProviderMap,
+  pageTextSchema: Stagehand.pageTextSchema,
+  providerEnvVarMap: Stagehand.providerEnvVarMap,
+  toGeminiSchema: Stagehand.toGeminiSchema,
+  toJsonSchema: Stagehand.toJsonSchema,
+  transformSchema: Stagehand.transformSchema,
+  trimTrailingTextNode: Stagehand.trimTrailingTextNode,
+  validateZodSchema: Stagehand.validateZodSchema,
+  ...publicErrorTypes,
+} as const;
+
+type StagehandExports = typeof Stagehand & {
+  default: typeof StagehandDefaultExport;
+};
+
+type PublicAPI = {
+  [K in keyof typeof publicApiShape]: StagehandExports[K];
+};
+
+describe("Stagehand public API export surface", () => {
+  it("public API shape matches module exports", () => {
+    const _check: PublicAPI = publicApiShape;
+    void _check;
+  });
+
+  it("does not expose unexpected top-level exports", () => {
+    const expected = Object.keys(publicApiShape).sort();
+    const actual = Object.keys(Stagehand).sort();
+    expect(actual).toStrictEqual(expected);
+  });
+});