[STG-1808] Deprecate Browserbase project ID

.changeset/yummy-poets-fail.md

@@ -0,0 +1,6 @@
+---
+"@browserbasehq/stagehand-server-v3": patch
+"@browserbasehq/stagehand": patch
+---
+
+Deprecate Browserbase project ID configuration.

packages/core/lib/v3/types/public/api.ts

@@ -298,7 +298,11 @@ export const BrowserbaseRegionSchema = z
 /** Browserbase session creation parameters */
 export const BrowserbaseSessionCreateParamsSchema = z
   .object({
-    projectId: z.string().optional(),
+    projectId: z.string().optional().meta({
+      deprecated: true,
+      description:
+        "Deprecated. Browserbase API keys are now project-scoped, so this field is no longer required.",
+    }),
     browserSettings: BrowserbaseBrowserSettingsSchema.optional(),
     extensionId: z.string().optional(),
     keepAlive: z.boolean().optional(),
@@ -975,7 +979,8 @@ export const openApiSecuritySchemes = {
     type: "apiKey",
     in: "header",
     name: "x-bb-project-id",
-    description: "Browserbase project ID",
+    description:
+      "Deprecated. Browserbase API keys are now project-scoped, so this header is no longer required.",
   },
   ModelApiKey: {
     type: "apiKey",

packages/server-v3/openapi.v3.yaml

@@ -32,7 +32,8 @@ components:
       type: apiKey
       in: header
       name: x-bb-project-id
-      description: Browserbase project ID
+      description: Deprecated. Browserbase API keys are now project-scoped, so this
+        header is no longer required.
     ModelApiKey:
       type: apiKey
       in: header
@@ -428,6 +429,9 @@ components:
       type: object
       properties:
         projectId:
+          deprecated: true
+          description: Deprecated. Browserbase API keys are now project-scoped, so this
+            field is no longer required.
           type: string
         browserSettings:
           $ref: "#/components/schemas/BrowserbaseBrowserSettings"
@@ -1469,6 +1473,9 @@ components:
       type: object
       properties:
         projectId:
+          deprecated: true
+          description: Deprecated. Browserbase API keys are now project-scoped, so this
+            field is no longer required.
           type: string
         browserSettings:
           $ref: "#/components/schemas/BrowserbaseBrowserSettingsOutput"

packages/server-v3/src/lib/stream.ts

@@ -51,18 +51,16 @@ export async function createStreamingResponse<TV3>({
   const browserType = sessionConfig.browserType ?? "local";
 
   let browserbaseApiKey = sessionConfig.browserbaseApiKey;
-  let browserbaseProjectId = sessionConfig.browserbaseProjectId;
+  const browserbaseProjectId = sessionConfig.browserbaseProjectId;
 
   if (browserType === "browserbase") {
     browserbaseApiKey =
       browserbaseApiKey ?? getOptionalHeader(request, "x-bb-api-key");
-    browserbaseProjectId =
-      browserbaseProjectId ?? getOptionalHeader(request, "x-bb-project-id");
 
     if (!browserbaseApiKey || !browserbaseProjectId) {
       return reply.status(StatusCodes.BAD_REQUEST).send({
         error:
-          "Browserbase API key and project ID are required for browserbase sessions",
+          "Browserbase API key and resolved project ID are required for browserbase sessions",
       });
     }
   }

packages/server-v3/src/routes/v1/sessions/start.ts

@@ -112,13 +112,12 @@ const startRouteHandler: RouteHandler = withErrorHandling(
     const browserType = browser?.type ?? "browserbase";
 
     let bbApiKey: string | undefined;
-    let bbProjectId: string | undefined;
+    let browserbaseProjectId: string | undefined;
     let browserbaseSessionId: string | undefined;
     let connectUrl: string | undefined;
 
     if (browserType === "browserbase") {
       bbApiKey = getOptionalHeader(request, "x-bb-api-key");
-      bbProjectId = getOptionalHeader(request, "x-bb-project-id");
 
       if (!bbApiKey) {
         return error(
@@ -132,6 +131,7 @@ const startRouteHandler: RouteHandler = withErrorHandling(
       if (browserbaseSessionID) {
         const existing = await bb.sessions.retrieve(browserbaseSessionID);
         browserbaseSessionId = existing?.id;
+        browserbaseProjectId = existing?.projectId;
         connectUrl = existing?.connectUrl;
         if (!browserbaseSessionId) {
           return error(reply, "Failed to retrieve browserbase session");
@@ -140,10 +140,7 @@ const startRouteHandler: RouteHandler = withErrorHandling(
           return error(reply, "Browserbase session missing connectUrl");
         }
       } else {
-        const resolvedProjectId =
-          browserbaseSessionCreateParams?.projectId ?? bbProjectId;
         const createPayload = {
-          ...(resolvedProjectId ? { projectId: resolvedProjectId } : {}),
           ...browserbaseSessionCreateParams,
           browserSettings: {
             ...(browserbaseSessionCreateParams?.browserSettings ?? {}),
@@ -164,6 +161,7 @@ const startRouteHandler: RouteHandler = withErrorHandling(
         )) as SessionRetrieveResponse;
 
         browserbaseSessionId = created?.id;
+        browserbaseProjectId = created?.projectId;
         connectUrl = created?.connectUrl;
         if (!browserbaseSessionId) {
           return error(reply, "Failed to create browserbase session");
@@ -189,7 +187,7 @@ const startRouteHandler: RouteHandler = withErrorHandling(
           ? (browserbaseSessionId ?? browserbaseSessionID)
           : undefined,
       browserbaseApiKey: bbApiKey,
-      browserbaseProjectId: bbProjectId,
+      browserbaseProjectId,
       modelName,
       domSettleTimeoutMs,
       verbose,

stainless.yml

@@ -229,8 +229,8 @@ client_settings:
     BROWSERBASE_PROJECT_ID:
       type: string
       read_env: BROWSERBASE_PROJECT_ID
-      description: Your [Browserbase Project ID](https://www.browserbase.com/settings)
-      nullable: false
+      description: Deprecated. Browserbase API keys are now project-scoped, so this value is no longer required.
+      nullable: true
       auth:
         security_scheme: BBProjectIdAuth
     MODEL_API_KEY: