Tidy: deprecate + rename init/constructor

.changeset/gorgeous-readers-rush.md

@@ -0,0 +1,7 @@
+---
+"@browserbasehq/stagehand": minor
+---
+
+- Deprecate fields in `init` in favor of constructor options
+- Deprecate `initFromPage` in favor of `browserbaseResumeSessionID` in constructor
+- Rename `browserBaseSessionCreateParams` -> `browserbaseSessionCreateParams`

README.md

@@ -141,7 +141,7 @@ This constructor is used to create an instance of Stagehand.
   - `domSettleTimeoutMs`: an `integer` that specifies the timeout in milliseconds for waiting for the DOM to settle. Defaults to 30000 (30 seconds).
   - `apiKey`: (optional) your Browserbase API key. Defaults to `BROWSERBASE_API_KEY` environment variable.
   - `projectId`: (optional) your Browserbase project ID. Defaults to `BROWSERBASE_PROJECT_ID` environment variable.
-  - `browserBaseSessionCreateParams`: configuration options for creating new Browserbase sessions.
+  - `browserbaseSessionCreateParams`: configuration options for creating new Browserbase sessions.
   - `browserbaseResumeSessionID`: ID of an existing Browserbase session to resume.
   - `logger`: a function that handles log messages. Useful for custom logging implementations.
   - `verbose`: an `integer` that enables several levels of logging during automation:
@@ -184,11 +184,14 @@ This constructor is used to create an instance of Stagehand.
 
 `init()` asynchronously initializes the Stagehand instance. It should be called before any other methods.
 
+> [!WARNING]  
+> Passing parameters to `init()` is deprecated and will be removed in the next major version. Use the constructor options instead.
+
 - **Arguments:**
 
-  - `modelName`: (optional) an `AvailableModel` string to specify the model to use. This will be used for all other methods unless overridden.
-  - `modelClientOptions`: (optional) configuration options for the model client
-  - `domSettleTimeoutMs`: (optional) timeout in milliseconds for waiting for the DOM to settle
+  - `modelName`: (**deprecated**, optional) an `AvailableModel` string to specify the model to use. This will be used for all other methods unless overridden.
+  - `modelClientOptions`: (**deprecated**, optional) configuration options for the model client
+  - `domSettleTimeoutMs`: (**deprecated**, optional) timeout in milliseconds for waiting for the DOM to settle
 
 - **Returns:**
 
@@ -198,7 +201,7 @@ This constructor is used to create an instance of Stagehand.
 
 - **Example:**
   ```javascript
-  await stagehand.init({ modelName: "gpt-4o" });
+  await stagehand.init();
   ```
 
 #### `act()`

evals/utils.ts

@@ -30,12 +30,14 @@ export const initStagehand = async ({
 }) => {
   const stagehand = new Stagehand({
     ...defaultStagehandOptions,
+    modelName,
+    domSettleTimeoutMs,
     logger: (logLine: LogLine) => {
       logger.log(logLine);
     },
   });
   logger.init(stagehand);
-  const initResponse = await stagehand.init({ modelName, domSettleTimeoutMs });
+  const initResponse = await stagehand.init();
   return { stagehand, logger, initResponse };
 };
 

examples/example.ts

@@ -8,9 +8,10 @@ async function example() {
     debugDom: true,
     enableCaching: false,
     modelName: "claude-3-5-sonnet-latest",
+    domSettleTimeoutMs: 10_000,
   });
 
-  await stagehand.init({ domSettleTimeoutMs: 3000 });
+  await stagehand.init();
   await stagehand.page.goto("https://www.mycmh.org/locations/");
 
   const result = await stagehand.extract({

examples/parameterizeApiKey.ts

@@ -23,12 +23,7 @@ async function example() {
     },
   });
 
-  await stagehand.init({
-    modelName: "gpt-4o",
-    modelClientOptions: {
-      apiKey: process.env.USE_OPENAI_API_KEY,
-    },
-  });
+  await stagehand.init();
   await stagehand.page.goto("https://github.com./browserbase/stagehand");
   await stagehand.act({ action: "click on the contributors" });
   const contributor = await stagehand.extract({

lib/index.ts

@@ -316,7 +316,7 @@ export class Stagehand {
   private logger: (logLine: LogLine) => void;
   private externalLogger?: (logLine: LogLine) => void;
   private domSettleTimeoutMs: number;
-  private browserBaseSessionCreateParams?: Browserbase.Sessions.SessionCreateParams;
+  private browserbaseSessionCreateParams?: Browserbase.Sessions.SessionCreateParams;
   private enableCaching: boolean;
   private variables: { [key: string]: unknown };
   private browserbaseResumeSessionID?: string;
@@ -336,7 +336,7 @@ export class Stagehand {
       llmProvider,
       headless,
       logger,
-      browserBaseSessionCreateParams,
+      browserbaseSessionCreateParams,
       domSettleTimeoutMs,
       enableCaching,
       browserbaseResumeSessionID,
@@ -364,25 +364,26 @@ export class Stagehand {
     );
     this.domSettleTimeoutMs = domSettleTimeoutMs ?? 30_000;
     this.headless = headless ?? false;
-    this.browserBaseSessionCreateParams = browserBaseSessionCreateParams;
+    this.browserbaseSessionCreateParams = browserbaseSessionCreateParams;
     this.browserbaseResumeSessionID = browserbaseResumeSessionID;
   }
 
-  async init({
-    modelName,
-    modelClientOptions,
-    domSettleTimeoutMs,
-  }: InitOptions = {}): Promise<InitResult> {
-    const llmClient = modelName
-      ? this.llmProvider.getClient(modelName, modelClientOptions)
-      : this.llmClient;
+  async init(
+    /** @deprecated Use constructor options instead */
+    initOptions?: InitOptions,
+  ): Promise<InitResult> {
+    if (initOptions) {
+      console.warn(
+        "Passing parameters to init() is deprecated and will be removed in the next major version. Use constructor options instead.",
+      );
+    }
     const { context, debugUrl, sessionUrl, contextPath } = await getBrowser(
       this.apiKey,
       this.projectId,
       this.env,
       this.headless,
       this.logger,
-      this.browserBaseSessionCreateParams,
+      this.browserbaseSessionCreateParams,
       this.browserbaseResumeSessionID,
     ).catch((e) => {
       console.error("Error in init:", e);
@@ -399,7 +400,6 @@ export class Stagehand {
     // Redundant but needed for users who are re-connecting to a previously-created session
     await this.page.waitForLoadState("domcontentloaded");
     await this._waitForSettledDom();
-    this.domSettleTimeoutMs = domSettleTimeoutMs ?? this.domSettleTimeoutMs;
 
     // Overload the page.goto method
     const originalGoto = this.page.goto.bind(this.page);
@@ -431,7 +431,7 @@ export class Stagehand {
       waitForSettledDom: this._waitForSettledDom.bind(this),
       startDomDebug: this.startDomDebug.bind(this),
       cleanupDomDebug: this.cleanupDomDebug.bind(this),
-      llmClient,
+      llmClient: this.llmClient,
     });
 
     this.extractHandler = new StagehandExtractHandler({
@@ -442,7 +442,7 @@ export class Stagehand {
       cleanupDomDebug: this.cleanupDomDebug.bind(this),
       llmProvider: this.llmProvider,
       verbose: this.verbose,
-      llmClient,
+      llmClient: this.llmClient,
     });
 
     this.observeHandler = new StagehandObserveHandler({
@@ -453,23 +453,21 @@ export class Stagehand {
       cleanupDomDebug: this.cleanupDomDebug.bind(this),
       llmProvider: this.llmProvider,
       verbose: this.verbose,
-      llmClient,
+      llmClient: this.llmClient,
     });
 
-    this.llmClient = llmClient;
     return { debugUrl, sessionUrl };
   }
 
+  /** @deprecated initFromPage is deprecated and will be removed in the next major version. */
   async initFromPage({
     page,
-    modelName,
-    modelClientOptions,
   }: InitFromPageOptions): Promise<InitFromPageResult> {
+    console.warn(
+      "initFromPage is deprecated and will be removed in the next major version. To instantiate from a page, use `browserbaseResumeSessionID` in the constructor.",
+    );
     this.page = page;
     this.context = page.context();
-    this.llmClient = modelName
-      ? this.llmProvider.getClient(modelName, modelClientOptions)
-      : this.llmClient;
 
     const originalGoto = this.page.goto.bind(this.page);
     this.page.goto = async (url: string, options?: GotoOptions) => {

types/stagehand.ts

@@ -15,7 +15,7 @@ export interface ConstructorParams {
   headless?: boolean;
   logger?: (message: LogLine) => void;
   domSettleTimeoutMs?: number;
-  browserBaseSessionCreateParams?: Browserbase.Sessions.SessionCreateParams;
+  browserbaseSessionCreateParams?: Browserbase.Sessions.SessionCreateParams;
   enableCaching?: boolean;
   browserbaseResumeSessionID?: string;
   modelName?: AvailableModel;
@@ -28,8 +28,11 @@ export interface InitResult {
 }
 
 export interface InitOptions {
+  /** @deprecated Pass this into the Stagehand constructor instead. This will be removed in the next major version. */
   modelName?: AvailableModel;
+  /** @deprecated Pass this into the Stagehand constructor instead. This will be removed in the next major version. */
   modelClientOptions?: ClientOptions;
+  /** @deprecated Pass this into the Stagehand constructor instead. This will be removed in the next major version. */
   domSettleTimeoutMs?: number;
 }
 
@@ -40,7 +43,9 @@ export interface InitResult {
 
 export interface InitFromPageOptions {
   page: Page;
+  /** @deprecated Pass this into the Stagehand constructor instead. This will be removed in the next major version. */
   modelName?: AvailableModel;
+  /** @deprecated Pass this into the Stagehand constructor instead. This will be removed in the next major version. */
   modelClientOptions?: ClientOptions;
 }