Support optional JSON headers via environment config

Co-authored-by: Shri Sukhani <shrisukhani@users.noreply.github.com>

Author: cursoragent

hyperbrowser/config.py

@@ -1,4 +1,5 @@
 from dataclasses import dataclass
+import json
 from typing import Dict, Mapping, Optional
 import os
 
@@ -49,4 +50,18 @@ def from_env(cls) -> "ClientConfig":
         base_url = os.environ.get(
             "HYPERBROWSER_BASE_URL", "https://api.hyperbrowser.ai"
         )
-        return cls(api_key=api_key, base_url=base_url)
+        headers = None
+        raw_headers = os.environ.get("HYPERBROWSER_HEADERS")
+        if raw_headers:
+            try:
+                parsed_headers = json.loads(raw_headers)
+            except json.JSONDecodeError as exc:
+                raise HyperbrowserError(
+                    "HYPERBROWSER_HEADERS must be valid JSON object"
+                ) from exc
+            if not isinstance(parsed_headers, dict):
+                raise HyperbrowserError(
+                    "HYPERBROWSER_HEADERS must be a JSON object of string pairs"
+                )
+            headers = parsed_headers
+        return cls(api_key=api_key, base_url=base_url, headers=headers)

tests/test_config.py

@@ -32,6 +32,36 @@ def test_client_config_from_env_reads_api_key_and_base_url(monkeypatch):
     assert config.base_url == "https://example.local"
 
 
+def test_client_config_from_env_reads_headers(monkeypatch):
+    monkeypatch.setenv("HYPERBROWSER_API_KEY", "test-key")
+    monkeypatch.setenv("HYPERBROWSER_HEADERS", '{"X-Request-Id":"abc123"}')
+
+    config = ClientConfig.from_env()
+
+    assert config.headers == {"X-Request-Id": "abc123"}
+
+
+def test_client_config_from_env_rejects_invalid_headers_json(monkeypatch):
+    monkeypatch.setenv("HYPERBROWSER_API_KEY", "test-key")
+    monkeypatch.setenv("HYPERBROWSER_HEADERS", "{invalid")
+
+    with pytest.raises(
+        HyperbrowserError, match="HYPERBROWSER_HEADERS must be valid JSON object"
+    ):
+        ClientConfig.from_env()
+
+
+def test_client_config_from_env_rejects_non_object_headers_json(monkeypatch):
+    monkeypatch.setenv("HYPERBROWSER_API_KEY", "test-key")
+    monkeypatch.setenv("HYPERBROWSER_HEADERS", '["not-an-object"]')
+
+    with pytest.raises(
+        HyperbrowserError,
+        match="HYPERBROWSER_HEADERS must be a JSON object of string pairs",
+    ):
+        ClientConfig.from_env()
+
+
 def test_client_config_from_env_normalizes_base_url(monkeypatch):
     monkeypatch.setenv("HYPERBROWSER_API_KEY", "test-key")
     monkeypatch.setenv("HYPERBROWSER_BASE_URL", " https://example.local/ ")