[STG-1808] Prefer STAGEHAND_API_URL env fallback

Author: monadoid

src/Client.php

@@ -47,9 +47,9 @@ public function __construct(
             'MODEL_API_KEY'
         ));
 
-        $baseUrl ??= Util::getenv(
-            'STAGEHAND_BASE_URL'
-        ) ?: 'https://api.stagehand.browserbase.com';
+        $baseUrl ??= Util::getenv('STAGEHAND_API_URL')
+            ?: Util::getenv('STAGEHAND_BASE_URL')
+                ?: 'https://api.stagehand.browserbase.com';
 
         $options = RequestOptions::parse(
             RequestOptions::with(

tests/ClientTest.php

@@ -14,17 +14,65 @@
  */
 class ClientTest extends TestCase
 {
-    public function testDefaultHeaders(): void
+    public function testBaseUrlUsesStagehandAPIUrlEnv(): void
     {
-        $transporter = new Client;
-        $mockRsp = Psr17FactoryDiscovery::findResponseFactory()
-            ->createResponse()
-            ->withStatus(200)
-            ->withHeader('Content-Type', 'application/json')
-            ->withBody(Psr17FactoryDiscovery::findStreamFactory()->createStream(json_encode([], flags: Util::JSON_ENCODE_FLAGS) ?: ''))
-        ;
+        $this->withEnv(
+            [
+                'STAGEHAND_API_URL' => 'http://localhost:5000/from-api-env',
+                'STAGEHAND_BASE_URL' => 'http://localhost:5000/from-base-env',
+            ],
+            function (): void {
+                $transporter = $this->mockTransport();
 
-        $transporter->setDefaultResponse($mockRsp);
+                $client = new \Stagehand\Client(
+                    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(
+                    'http://localhost:5000/from-api-env/v1/sessions/start',
+                    (string) $requested->getUri()
+                );
+            },
+        );
+    }
+
+    public function testBaseUrlUsesLegacyStagehandBaseUrlEnv(): void
+    {
+        $this->withEnv(
+            [
+                'STAGEHAND_API_URL' => null,
+                'STAGEHAND_BASE_URL' => 'http://localhost:5000/from-base-env',
+            ],
+            function (): void {
+                $transporter = $this->mockTransport();
+
+                $client = new \Stagehand\Client(
+                    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(
+                    'http://localhost:5000/from-base-env/v1/sessions/start',
+                    (string) $requested->getUri()
+                );
+            },
+        );
+    }
+
+    public function testDefaultHeaders(): void
+    {
+        $transporter = $this->mockTransport();
 
         $client = new \Stagehand\Client(
             baseUrl: 'http://localhost',
@@ -43,4 +91,43 @@ public function testDefaultHeaders(): void
             $this->assertNotEmpty($sent);
         }
     }
+
+    private function mockTransport(): Client
+    {
+        $transporter = new Client;
+        $mockRsp = Psr17FactoryDiscovery::findResponseFactory()
+            ->createResponse()
+            ->withStatus(200)
+            ->withHeader('Content-Type', 'application/json')
+            ->withBody(Psr17FactoryDiscovery::findStreamFactory()->createStream(json_encode([], flags: Util::JSON_ENCODE_FLAGS) ?: ''))
+        ;
+
+        $transporter->setDefaultResponse($mockRsp);
+
+        return $transporter;
+    }
+
+    /**
+     * @param array<string, string|null> $vars
+     */
+    private function withEnv(array $vars, callable $callback): void
+    {
+        $oldValues = [];
+        foreach ($vars as $key => $_) {
+            $value = getenv($key);
+            $oldValues[$key] = false === $value ? null : $value;
+        }
+
+        try {
+            foreach ($vars as $key => $value) {
+                null === $value ? putenv($key) : putenv("{$key}={$value}");
+            }
+
+            $callback();
+        } finally {
+            foreach ($oldValues as $key => $value) {
+                null === $value ? putenv($key) : putenv("{$key}={$value}");
+            }
+        }
+    }
 }