release: 0.1.0

.github/workflows/release-doctor.yml

@@ -9,7 +9,7 @@ jobs:
   release_doctor:
     name: release doctor
     runs-on: ubuntu-latest
-    if: github.repository == 'stainless-sdks/stagehand-php' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch' || startsWith(github.head_ref, 'release-please') || github.head_ref == 'next')
+    if: github.repository == 'browserbase/stagehand-php' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch' || startsWith(github.head_ref, 'release-please') || github.head_ref == 'next')
 
     steps:
       - uses: actions/checkout@v4

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.0.1"
+  ".": "0.1.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 7
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase%2Fstagehand-0c12f985340be2a9287e8e01ff8733f7f2d02e019149d1ae95f1a8f8798c6690.yml
-openapi_spec_hash: efb79934e1dc63763dd4e8493b825273
-config_hash: 5f3345d1d825e49f896f3b0e493e6938
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase%2Fstagehand-2c88c6d890406ff8a5f1bca692264fb9af4bc4fe64df0986e06d3386fc6d6fcb.yml
+openapi_spec_hash: dc6ea17f8152708dc0a390c7f86b1a5d
+config_hash: a17b6052ac65237b7b8e145f4f692d3c

CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.0 (2025-12-16)
+
+Full Changelog: [v0.0.1...v0.1.0](https://github.com/browserbase/stagehand-php/compare/v0.0.1...v0.1.0)
+
+### Features
+
+* **api:** manual updates ([45de578](https://github.com/browserbase/stagehand-php/commit/45de5783970107d40cb031f867e6844a7e03acfb))
+* **api:** manual updates ([1a693a0](https://github.com/browserbase/stagehand-php/commit/1a693a00b3455b5368a4f8e480c6a10d69f52d57))
+* **api:** manual updates ([9cb66f2](https://github.com/browserbase/stagehand-php/commit/9cb66f25e24c9584566aad1d8cc5e2f048ac27e1))
+* **api:** manual updates ([b1d2b2c](https://github.com/browserbase/stagehand-php/commit/b1d2b2ccbb10c56928f6ae81a914770b70411053))
+* **api:** manual updates ([9080e0a](https://github.com/browserbase/stagehand-php/commit/9080e0a09f5ccd2d34ee480ddaea25e21058664e))
+* **api:** tweak branding and fix some config fields ([90c7197](https://github.com/browserbase/stagehand-php/commit/90c71979a68c674d6c7acc99f44bca480bb0969b))
+
+
+### Chores
+
+* configure new SDK language ([83f228c](https://github.com/browserbase/stagehand-php/commit/83f228c57bb2a41078c00161a01aa6be4e36074e))
+* **internal:** codegen related update ([582a585](https://github.com/browserbase/stagehand-php/commit/582a58509d679383e90422b7f9d836afa9277354))
+* **internal:** codegen related update ([f320af0](https://github.com/browserbase/stagehand-php/commit/f320af00744b1ef4ea2007ca9b80d58f147061aa))

README.md

@@ -5,34 +5,38 @@
 >
 > This library has not yet been exhaustively tested in production environments and may be missing some features you'd expect in a stable release. As we continue development, there may be breaking changes that require updates to your code.
 >
-> **We'd love your feedback!** Please share any suggestions, bug reports, feature requests, or general thoughts by [filing an issue](https://www.github.com/stainless-sdks/stagehand-php/issues/new).
+> **We'd love your feedback!** Please share any suggestions, bug reports, feature requests, or general thoughts by [filing an issue](https://www.github.com/browserbase/stagehand-php/issues/new).
 
 The Stagehand PHP library provides convenient access to the Stagehand REST API from any PHP 8.1.0+ application.
 
 It is generated with [Stainless](https://www.stainless.com/).
 
 ## Documentation
 
-The REST API documentation can be found on [browserbase.com](https://browserbase.com).
+The REST API documentation can be found on [docs.stagehand.dev](https://docs.stagehand.dev).
 
 ## Installation
 
 To use this package, install via Composer by adding the following to your application's `composer.json`:
 
+<!-- x-release-please-start-version -->
+
 ```json
 {
   "repositories": [
     {
       "type": "vcs",
-      "url": "git@github.com:stainless-sdks/stagehand-php.git"
+      "url": "git@github.com:browserbase/stagehand-php.git"
     }
   ],
   "require": {
-    "org-placeholder/stagehand": "dev-main"
+    "browserbase/stagehand": "dev-main"
   }
 }
 ```
 
+<!-- x-release-please-end -->
+
 ## Usage
 
 This library uses named parameters to specify optional arguments.
@@ -44,13 +48,19 @@ Parameters with a default value must be set by name.
 use Stagehand\Client;
 
 $client = new Client(
-  apiKey: getenv('STAGEHAND_API_KEY') ?: 'My API Key',
-  environment: 'environment_1',
+  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',
 );
 
-$response = $client->sessions->start(env: 'LOCAL');
+$response = $client->sessions->act(
+  '00000000-your-session-id-000000000000',
+  input: 'click the first link on the page',
+);
 
-var_dump($response->available);
+var_dump($response->actions);
 ```
 
 ### Value Objects
@@ -70,7 +80,10 @@ When the library is unable to connect to the API, or if the API returns a non-su
 use Stagehand\Core\Exceptions\APIConnectionException;
 
 try {
-  $response = $client->sessions->start(env: 'LOCAL');
+  $response = $client->sessions->start(
+    browserbaseAPIKey: '<your API key here>',
+    browserbaseProjectID: '<your project ID here>',
+  );
 } catch (APIConnectionException $e) {
   echo "The server could not be reached", PHP_EOL;
   var_dump($e->getPrevious());
@@ -117,7 +130,9 @@ $client = new Client(maxRetries: 0);
 
 // Or, configure per-request:
 $result = $client->sessions->start(
-  env: 'LOCAL', requestOptions: RequestOptions::with(maxRetries: 5)
+  browserbaseAPIKey: '<your API key here>',
+  browserbaseProjectID: '<your project ID here>',
+  requestOptions: RequestOptions::with(maxRetries: 5),
 );
 ```
 
@@ -137,7 +152,8 @@ Note: the `extra*` parameters of the same name overrides the documented paramete
 use Stagehand\RequestOptions;
 
 $response = $client->sessions->start(
-  env: 'LOCAL',
+  browserbaseAPIKey: '<your API key here>',
+  browserbaseProjectID: '<your project ID here>',
   requestOptions: RequestOptions::with(
     extraQueryParams: ['my_query_parameter' => 'value'],
     extraBodyParams: ['my_body_parameter' => 'value'],
@@ -178,4 +194,4 @@ PHP 8.1.0 or higher.
 
 ## Contributing
 
-See [the contributing documentation](https://github.com/stainless-sdks/stagehand-php/tree/main/CONTRIBUTING.md).
+See [the contributing documentation](https://github.com/browserbase/stagehand-php/tree/main/CONTRIBUTING.md).

composer.json

@@ -29,7 +29,7 @@
     "sort-packages": true
   },
   "description": "Stagehand PHP SDK",
-  "name": "org-placeholder/stagehand",
+  "name": "browserbase/stagehand",
   "require": {
     "php": "^8.1",
     "php-http/discovery": "^1",

src/Client.php

@@ -12,18 +12,30 @@
 
 class Client extends BaseClient
 {
-    public string $apiKey;
+    public string $browserbaseAPIKey;
+
+    public string $browserbaseProjectID;
+
+    public string $modelAPIKey;
 
     /**
      * @api
      */
     public SessionsService $sessions;
 
-    public function __construct(?string $apiKey = null, ?string $baseUrl = null)
-    {
-        $this->apiKey = (string) ($apiKey ?? getenv('STAGEHAND_API_KEY'));
+    public function __construct(
+        ?string $browserbaseAPIKey = null,
+        ?string $browserbaseProjectID = null,
+        ?string $modelAPIKey = null,
+        ?string $baseUrl = null,
+    ) {
+        $this->browserbaseAPIKey = (string) ($browserbaseAPIKey ?? getenv('BROWSERBASE_API_KEY'));
+        $this->browserbaseProjectID = (string) ($browserbaseProjectID ?? getenv('BROWSERBASE_PROJECT_ID'));
+        $this->modelAPIKey = (string) ($modelAPIKey ?? getenv('MODEL_API_KEY'));
 
-        $baseUrl ??= getenv('STAGEHAND_BASE_URL') ?: 'http://localhost:3000/v1';
+        $baseUrl ??= getenv(
+            'STAGEHAND_BASE_URL'
+        ) ?: 'https://api.stagehand.browserbase.com/v1';
 
         $options = RequestOptions::with(
             uriFactory: Psr17FactoryDiscovery::findUriFactory(),
@@ -52,8 +64,24 @@ public function __construct(?string $apiKey = null, ?string $baseUrl = null)
     }
 
     /** @return array<string,string> */
-    protected function authHeaders(): array
+    protected function bbAPIKeyAuth(): array
+    {
+        return $this->browserbaseAPIKey ? [
+            'x-bb-api-key' => $this->browserbaseAPIKey,
+        ] : [];
+    }
+
+    /** @return array<string,string> */
+    protected function bbProjectIDAuth(): array
+    {
+        return $this->browserbaseProjectID ? [
+            'x-bb-project-id' => $this->browserbaseProjectID,
+        ] : [];
+    }
+
+    /** @return array<string,string> */
+    protected function llmModelAPIKeyAuth(): array
     {
-        return $this->apiKey ? ['Authorization' => "Bearer {$this->apiKey}"] : [];
+        return $this->modelAPIKey ? ['x-model-api-key' => $this->modelAPIKey] : [];
     }
 }

src/Core/BaseClient.php

@@ -89,7 +89,23 @@ public function request(
     }
 
     /** @return array<string,string> */
-    abstract protected function authHeaders(): array;
+    protected function authHeaders(): array
+    {
+        return [
+            ...$this->bbAPIKeyAuth(),
+            ...$this->bbProjectIDAuth(),
+            ...$this->llmModelAPIKeyAuth(),
+        ];
+    }
+
+    /** @return array<string,string> */
+    abstract protected function bbAPIKeyAuth(): array;
+
+    /** @return array<string,string> */
+    abstract protected function bbProjectIDAuth(): array;
+
+    /** @return array<string,string> */
+    abstract protected function llmModelAPIKeyAuth(): array;
 
     /**
      * @internal

src/ServiceContracts/SessionsContract.php

@@ -15,7 +15,6 @@
 use Stagehand\Sessions\SessionExtractResponse\Extraction;
 use Stagehand\Sessions\SessionNavigateParams\Options\WaitUntil;
 use Stagehand\Sessions\SessionNavigateResponse;
-use Stagehand\Sessions\SessionStartParams\Env;
 use Stagehand\Sessions\SessionStartResponse;
 
 interface SessionsContract
@@ -188,27 +187,21 @@ public function observe(
     /**
      * @api
      *
-     * @param 'LOCAL'|'BROWSERBASE'|Env $env Environment to run the browser in
-     * @param string $apiKey API key for Browserbase (required when env=BROWSERBASE)
+     * @param string $browserbaseAPIKey API key for Browserbase Cloud
+     * @param string $browserbaseProjectID Project ID for Browserbase
      * @param int $domSettleTimeout Timeout in ms to wait for DOM to settle
-     * @param array{
-     *   headless?: bool
-     * } $localBrowserLaunchOptions Options for local browser launch
-     * @param string $model AI model to use for actions
-     * @param string $projectID Project ID for Browserbase (required when env=BROWSERBASE)
+     * @param string $model AI model to use for actions (must be prefixed with provider/)
      * @param bool $selfHeal Enable self-healing for failed actions
      * @param string $systemPrompt Custom system prompt for AI actions
      * @param int $verbose Logging verbosity level
      *
      * @throws APIException
      */
     public function start(
-        string|Env $env,
-        ?string $apiKey = null,
+        string $browserbaseAPIKey,
+        string $browserbaseProjectID,
         ?int $domSettleTimeout = null,
-        ?array $localBrowserLaunchOptions = null,
         ?string $model = null,
-        ?string $projectID = null,
         ?bool $selfHeal = null,
         ?string $systemPrompt = null,
         int $verbose = 0,

src/Services/SessionsRawService.php

@@ -27,7 +27,6 @@
 use Stagehand\Sessions\SessionNavigateResponse;
 use Stagehand\Sessions\SessionObserveParams;
 use Stagehand\Sessions\SessionStartParams;
-use Stagehand\Sessions\SessionStartParams\Env;
 use Stagehand\Sessions\SessionStartResponse;
 
 final class SessionsRawService implements SessionsRawContract
@@ -346,12 +345,10 @@ public function observe(
      * Returns a session ID that must be used for all subsequent requests.
      *
      * @param array{
-     *   env: 'LOCAL'|'BROWSERBASE'|Env,
-     *   apiKey?: string,
+     *   browserbaseAPIKey: string,
+     *   browserbaseProjectID: string,
      *   domSettleTimeout?: int,
-     *   localBrowserLaunchOptions?: array{headless?: bool},
      *   model?: string,
-     *   projectID?: string,
      *   selfHeal?: bool,
      *   systemPrompt?: string,
      *   verbose?: int,

src/Services/SessionsService.php

@@ -18,7 +18,6 @@
 use Stagehand\Sessions\SessionExtractResponse\Extraction;
 use Stagehand\Sessions\SessionNavigateParams\Options\WaitUntil;
 use Stagehand\Sessions\SessionNavigateResponse;
-use Stagehand\Sessions\SessionStartParams\Env;
 use Stagehand\Sessions\SessionStartResponse;
 
 final class SessionsService implements SessionsContract
@@ -299,40 +298,32 @@ public function observe(
      * Initializes a new Stagehand session with a browser instance.
      * Returns a session ID that must be used for all subsequent requests.
      *
-     * @param 'LOCAL'|'BROWSERBASE'|Env $env Environment to run the browser in
-     * @param string $apiKey API key for Browserbase (required when env=BROWSERBASE)
+     * @param string $browserbaseAPIKey API key for Browserbase Cloud
+     * @param string $browserbaseProjectID Project ID for Browserbase
      * @param int $domSettleTimeout Timeout in ms to wait for DOM to settle
-     * @param array{
-     *   headless?: bool
-     * } $localBrowserLaunchOptions Options for local browser launch
-     * @param string $model AI model to use for actions
-     * @param string $projectID Project ID for Browserbase (required when env=BROWSERBASE)
+     * @param string $model AI model to use for actions (must be prefixed with provider/)
      * @param bool $selfHeal Enable self-healing for failed actions
      * @param string $systemPrompt Custom system prompt for AI actions
      * @param int $verbose Logging verbosity level
      *
      * @throws APIException
      */
     public function start(
-        string|Env $env,
-        ?string $apiKey = null,
+        string $browserbaseAPIKey,
+        string $browserbaseProjectID,
         ?int $domSettleTimeout = null,
-        ?array $localBrowserLaunchOptions = null,
         ?string $model = null,
-        ?string $projectID = null,
         ?bool $selfHeal = null,
         ?string $systemPrompt = null,
         int $verbose = 0,
         ?RequestOptions $requestOptions = null,
     ): SessionStartResponse {
         $params = Util::removeNulls(
             [
-                'env' => $env,
-                'apiKey' => $apiKey,
+                'browserbaseAPIKey' => $browserbaseAPIKey,
+                'browserbaseProjectID' => $browserbaseProjectID,
                 'domSettleTimeout' => $domSettleTimeout,
-                'localBrowserLaunchOptions' => $localBrowserLaunchOptions,
                 'model' => $model,
-                'projectID' => $projectID,
                 'selfHeal' => $selfHeal,
                 'systemPrompt' => $systemPrompt,
                 'verbose' => $verbose,