[STG-1808] Prefer STAGEHAND_API_URL env fallback

Author: monadoid

examples/env.rb

@@ -23,11 +23,9 @@ def self.load!
     end
 
     missing = REQUIRED_KEYS.select { |key| ENV[key].to_s.empty? }
-    unless missing.empty?
-      raise "Missing required env vars: #{missing.join(', ')} (from examples/.env)"
-    end
+    return if missing.empty?
 
-    ENV["STAGEHAND_BASE_URL"] ||= ENV["STAGEHAND_API_URL"]
+    raise "Missing required env vars: #{missing.join(', ')} (from examples/.env)"
   end
 
   def self.find_env_path

lib/stagehand/client.rb

@@ -72,7 +72,7 @@ class Client < Stagehand::Internal::Transport::BaseClient
     # @param server [String] Server mode to use ("remote" or "local"). Defaults to "remote"
     #
     # @param base_url [String, nil] Override the default base URL for the API, e.g.,
-    # `"https://api.example.com/v2/"`. Defaults to `ENV["STAGEHAND_BASE_URL"]`
+    # `"https://api.example.com/v2/"`. Defaults to `ENV["STAGEHAND_API_URL"]`
     #
     # @param max_retries [Integer] Max number of retries to attempt after a failed retryable request.
     #
@@ -86,7 +86,7 @@ def initialize(
       browserbase_project_id: ENV["BROWSERBASE_PROJECT_ID"],
       model_api_key: ENV["MODEL_API_KEY"],
       server: "remote",
-      base_url: ENV["STAGEHAND_BASE_URL"],
+      base_url: ENV["STAGEHAND_API_URL"] || ENV["STAGEHAND_BASE_URL"],
       max_retries: self.class::DEFAULT_MAX_RETRIES,
       timeout: self.class::DEFAULT_TIMEOUT_IN_SECONDS,
       initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY,

rbi/stagehand/client.rbi

@@ -72,8 +72,8 @@ module Stagehand
       # Server mode to use ("remote" or "local"). Defaults to "remote"
       server: "remote",
       # Override the default base URL for the API, e.g.,
-      # `"https://api.example.com/v2/"`. Defaults to `ENV["STAGEHAND_BASE_URL"]`
-      base_url: ENV["STAGEHAND_BASE_URL"],
+      # `"https://api.example.com/v2/"`. Defaults to `ENV["STAGEHAND_API_URL"]`
+      base_url: ENV["STAGEHAND_API_URL"] || ENV["STAGEHAND_BASE_URL"],
       # Max number of retries to attempt after a failed retryable request.
       max_retries: Stagehand::Client::DEFAULT_MAX_RETRIES,
       timeout: Stagehand::Client::DEFAULT_TIMEOUT_IN_SECONDS,

test/stagehand/client_test.rb

@@ -34,6 +34,62 @@ def test_raises_on_missing_non_nullable_opts
     assert_match(/is required/, e.message)
   end
 
+  def test_client_base_url_from_stagehand_api_url
+    with_env("STAGEHAND_API_URL" => "http://localhost:5000/from/api/env", "STAGEHAND_BASE_URL" => nil) do
+      stagehand =
+        Stagehand::Client.new(
+          browserbase_api_key: "My Browserbase API Key",
+          browserbase_project_id: "My Browserbase Project ID",
+          model_api_key: "My Model API Key"
+        )
+
+      assert_equal("http://localhost:5000/from/api/env", stagehand.base_url.to_s)
+    end
+  end
+
+  def test_client_base_url_from_legacy_stagehand_base_url
+    with_env("STAGEHAND_API_URL" => nil, "STAGEHAND_BASE_URL" => "http://localhost:5000/from/base/env") do
+      stagehand =
+        Stagehand::Client.new(
+          browserbase_api_key: "My Browserbase API Key",
+          browserbase_project_id: "My Browserbase Project ID",
+          model_api_key: "My Model API Key"
+        )
+
+      assert_equal("http://localhost:5000/from/base/env", stagehand.base_url.to_s)
+    end
+  end
+
+  def test_client_base_url_prefers_stagehand_api_url
+    with_env(
+      "STAGEHAND_API_URL" => "http://localhost:5000/from/api/env",
+      "STAGEHAND_BASE_URL" => "http://localhost:5000/from/base/env"
+    ) do
+      stagehand =
+        Stagehand::Client.new(
+          browserbase_api_key: "My Browserbase API Key",
+          browserbase_project_id: "My Browserbase Project ID",
+          model_api_key: "My Model API Key"
+        )
+
+      assert_equal("http://localhost:5000/from/api/env", stagehand.base_url.to_s)
+    end
+  end
+
+  def with_env(vars)
+    old_values = vars.keys.to_h { |key| [key, ENV.fetch(key, nil)] }
+
+    vars.each do |key, value|
+      value.nil? ? ENV.delete(key) : ENV[key] = value
+    end
+
+    yield
+  ensure
+    old_values.each do |key, value|
+      value.nil? ? ENV.delete(key) : ENV[key] = value
+    end
+  end
+
   def test_client_default_request_default_retry_attempts
     stub_request(:post, "http://localhost/v1/sessions/start").to_return_json(status: 500, body: {})