Deprecate browserbase project ID (#58)

Co-authored-by: samfinton <samfinton@samLaptopm5.galaxus.box>

Author: monadoid

AGENTS.md

@@ -32,7 +32,6 @@ composer require browserbase/stagehand
 
 # Set environment variables
 export BROWSERBASE_API_KEY="your-bb-api-key"
-export BROWSERBASE_PROJECT_ID="your-bb-project-uuid"
 export MODEL_API_KEY="sk-proj-your-llm-api-key"
 
 # Run the example
@@ -45,7 +44,6 @@ use Stagehand\Client;
 
 $client = new Client(
     browserbaseAPIKey: getenv('BROWSERBASE_API_KEY'),
-    browserbaseProjectID: getenv('BROWSERBASE_PROJECT_ID'),
     modelAPIKey: getenv('MODEL_API_KEY'),
 );
 $startResponse = $client->sessions->start(model: 'openai/gpt-5-nano');

README.md

@@ -113,14 +113,12 @@ if (file_exists(__DIR__ . '/../.env')) {
 // Initialize the Stagehand client with API keys from environment variables
 $client = new Client(
     browserbaseAPIKey: getenv('BROWSERBASE_API_KEY') ?: throw new Exception('BROWSERBASE_API_KEY environment variable is required'),
-    browserbaseProjectID: getenv('BROWSERBASE_PROJECT_ID') ?: throw new Exception('BROWSERBASE_PROJECT_ID environment variable is required'),
     modelAPIKey: getenv('MODEL_API_KEY') ?: throw new Exception('MODEL_API_KEY environment variable is required'),
 );
 
 // Start a new session
 $startResponse = $client->sessions->start(
     browserbaseAPIKey: getenv('BROWSERBASE_API_KEY'),
-    browserbaseProjectID: getenv('BROWSERBASE_PROJECT_ID'),
     model: 'openai/gpt-4o',
 );
 echo "Session started: {$startResponse->data->sessionID}\n";
@@ -217,12 +215,11 @@ echo "Session ended\n";
 
 ### Running the Example
 
-Set the required environment variables and run the example script:
+Set the environment variables and run the example script:
 
 ```bash
 # Set your credentials
 export BROWSERBASE_API_KEY="your-browserbase-api-key"
-export BROWSERBASE_PROJECT_ID="your-browserbase-project-id"
 export MODEL_API_KEY="your-openai-api-key"
 
 # Install dependencies and run
@@ -248,9 +245,6 @@ use Stagehand\Client;
 
 $client = new Client(
   browserbaseAPIKey: getenv('BROWSERBASE_API_KEY') ?: 'My Browserbase API Key',
-  browserbaseProjectID: getenv(
-    'BROWSERBASE_PROJECT_ID'
-  ) ?: 'My Browserbase Project ID',
   modelAPIKey: getenv('MODEL_API_KEY') ?: 'My Model API Key',
 );
 

examples/basic.php

@@ -18,14 +18,12 @@
 // Initialize the Stagehand client with API keys from environment variables
 $client = new Client(
     browserbaseAPIKey: getenv('BROWSERBASE_API_KEY') ?: throw new Exception('BROWSERBASE_API_KEY environment variable is required'),
-    browserbaseProjectID: getenv('BROWSERBASE_PROJECT_ID') ?: throw new Exception('BROWSERBASE_PROJECT_ID environment variable is required'),
     modelAPIKey: getenv('MODEL_API_KEY') ?: throw new Exception('MODEL_API_KEY environment variable is required'),
 );
 
 // Start a new session
 $startResponse = $client->sessions->start(
     browserbaseAPIKey: getenv('BROWSERBASE_API_KEY'),
-    browserbaseProjectID: getenv('BROWSERBASE_PROJECT_ID'),
     model: 'openai/gpt-4o',
 );
 echo "Session started: {$startResponse->data->sessionID}\n";

src/Client.php

@@ -18,6 +18,10 @@ class Client extends BaseClient
 {
     public string $browserbaseAPIKey;
 
+    /**
+     * Deprecated. Browserbase API keys are now project-scoped, so this value is no longer required.
+     * Accepted for backwards compatibility; it is ignored.
+     */
     public string $browserbaseProjectID;
 
     public string $modelAPIKey;
@@ -40,9 +44,7 @@ public function __construct(
         $this->browserbaseAPIKey = (string) ($browserbaseAPIKey ?? Util::getenv(
             'BROWSERBASE_API_KEY'
         ));
-        $this->browserbaseProjectID = (string) ($browserbaseProjectID ?? Util::getenv(
-            'BROWSERBASE_PROJECT_ID'
-        ));
+        $this->browserbaseProjectID = (string) $browserbaseProjectID;
         $this->modelAPIKey = (string) ($modelAPIKey ?? Util::getenv(
             'MODEL_API_KEY'
         ));
@@ -85,7 +87,6 @@ protected function authHeaders(): array
     {
         return [
             ...$this->bbAPIKeyAuth(),
-            ...$this->bbProjectIDAuth(),
             ...$this->llmModelAPIKeyAuth(),
         ];
     }
@@ -101,9 +102,7 @@ protected function bbAPIKeyAuth(): array
     /** @return array<string,string> */
     protected function bbProjectIDAuth(): array
     {
-        return $this->browserbaseProjectID ? [
-            'x-bb-project-id' => $this->browserbaseProjectID,
-        ] : [];
+        return [];
     }
 
     /** @return array<string,string> */

tests/ClientTest.php

@@ -92,6 +92,24 @@ public function testDefaultHeaders(): void
         }
     }
 
+    public function testProjectIDHeaderIsOmitted(): void
+    {
+        $transporter = $this->mockTransport();
+
+        $client = new \Stagehand\Client(
+            baseUrl: 'http://localhost',
+            browserbaseAPIKey: 'My Browserbase API Key',
+            browserbaseProjectID: 'My Browserbase Project ID',
+            modelAPIKey: 'My Model API Key',
+            requestOptions: ['transporter' => $transporter],
+        );
+
+        $client->sessions->start(modelName: 'openai/gpt-5.4-mini');
+
+        $this->assertNotFalse($requested = $transporter->getRequests()[0] ?? false);
+        $this->assertSame('', $requested->getHeaderLine('x-bb-project-id'));
+    }
+
     private function mockTransport(): Client
     {
         $transporter = new Client;