feat: browser_pools: add start_url config (KERNEL-1217 PR 2)

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 112
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-b51c72a040c8dfea9c0693de6631feabfffe42922d5feb60b4ac0ee5c83bb8f4.yml
-openapi_spec_hash: 8b671cfe4debe8d9ad7c39ba5b0eaf6d
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-7d2d29d7598105d50e5118e0bc5ac654361a92cb95555705dbd1d236848e1456.yml
+openapi_spec_hash: 10002eae793e08f81932239bbc72b503
 config_hash: 08d55086449943a8fec212b870061a3f

browser.go

@@ -328,6 +328,9 @@ type BrowserNewResponse struct {
 	Profile Profile `json:"profile"`
 	// ID of the proxy associated with this browser session, if any.
 	ProxyID string `json:"proxy_id"`
+	// URL the session was asked to navigate to on creation, if any. Recorded for
+	// debugging — navigation is best-effort and may have failed.
+	StartURL string `json:"start_url"`
 	// Session usage metrics.
 	Usage BrowserUsage `json:"usage"`
 	// Initial browser window size in pixels with optional refresh rate. If omitted,
@@ -361,6 +364,7 @@ type BrowserNewResponse struct {
 		Pool               respjson.Field
 		Profile            respjson.Field
 		ProxyID            respjson.Field
+		StartURL           respjson.Field
 		Usage              respjson.Field
 		Viewport           respjson.Field
 		ExtraFields        map[string]respjson.Field
@@ -411,6 +415,9 @@ type BrowserGetResponse struct {
 	Profile Profile `json:"profile"`
 	// ID of the proxy associated with this browser session, if any.
 	ProxyID string `json:"proxy_id"`
+	// URL the session was asked to navigate to on creation, if any. Recorded for
+	// debugging — navigation is best-effort and may have failed.
+	StartURL string `json:"start_url"`
 	// Session usage metrics.
 	Usage BrowserUsage `json:"usage"`
 	// Initial browser window size in pixels with optional refresh rate. If omitted,
@@ -444,6 +451,7 @@ type BrowserGetResponse struct {
 		Pool               respjson.Field
 		Profile            respjson.Field
 		ProxyID            respjson.Field
+		StartURL           respjson.Field
 		Usage              respjson.Field
 		Viewport           respjson.Field
 		ExtraFields        map[string]respjson.Field
@@ -494,6 +502,9 @@ type BrowserUpdateResponse struct {
 	Profile Profile `json:"profile"`
 	// ID of the proxy associated with this browser session, if any.
 	ProxyID string `json:"proxy_id"`
+	// URL the session was asked to navigate to on creation, if any. Recorded for
+	// debugging — navigation is best-effort and may have failed.
+	StartURL string `json:"start_url"`
 	// Session usage metrics.
 	Usage BrowserUsage `json:"usage"`
 	// Initial browser window size in pixels with optional refresh rate. If omitted,
@@ -527,6 +538,7 @@ type BrowserUpdateResponse struct {
 		Pool               respjson.Field
 		Profile            respjson.Field
 		ProxyID            respjson.Field
+		StartURL           respjson.Field
 		Usage              respjson.Field
 		Viewport           respjson.Field
 		ExtraFields        map[string]respjson.Field
@@ -577,6 +589,9 @@ type BrowserListResponse struct {
 	Profile Profile `json:"profile"`
 	// ID of the proxy associated with this browser session, if any.
 	ProxyID string `json:"proxy_id"`
+	// URL the session was asked to navigate to on creation, if any. Recorded for
+	// debugging — navigation is best-effort and may have failed.
+	StartURL string `json:"start_url"`
 	// Session usage metrics.
 	Usage BrowserUsage `json:"usage"`
 	// Initial browser window size in pixels with optional refresh rate. If omitted,
@@ -610,6 +625,7 @@ type BrowserListResponse struct {
 		Pool               respjson.Field
 		Profile            respjson.Field
 		ProxyID            respjson.Field
+		StartURL           respjson.Field
 		Usage              respjson.Field
 		Viewport           respjson.Field
 		ExtraFields        map[string]respjson.Field
@@ -665,6 +681,12 @@ type BrowserNewParams struct {
 	// Optional proxy to associate to the browser session. Must reference a proxy
 	// belonging to the caller's org.
 	ProxyID param.Opt[string] `json:"proxy_id,omitzero"`
+	// Optional URL to navigate to immediately after the browser is created.
+	// Best-effort: failures to navigate do not fail browser creation. Any pre-existing
+	// tabs are reduced to a single tab which is then navigated. Accepts any URL
+	// Chromium can resolve, including chrome:// pages. Ignored when reusing an
+	// existing persistent session.
+	StartURL param.Opt[string] `json:"start_url,omitzero"`
 	// If true, launches the browser in stealth mode to reduce detection by anti-bot
 	// mechanisms.
 	Stealth param.Opt[bool] `json:"stealth,omitzero"`

browser_test.go

@@ -47,6 +47,7 @@ func TestBrowserNewWithOptionalParams(t *testing.T) {
 			SaveChanges: kernel.Bool(true),
 		},
 		ProxyID:        kernel.String("proxy_id"),
+		StartURL:       kernel.String("https://example.com"),
 		Stealth:        kernel.Bool(true),
 		TimeoutSeconds: kernel.Int(10),
 		Viewport: shared.BrowserViewportParam{

browserpool.go

@@ -196,6 +196,12 @@ type BrowserPoolBrowserPoolConfig struct {
 	// Optional proxy to associate to the browser session. Must reference a proxy
 	// belonging to the caller's org.
 	ProxyID string `json:"proxy_id"`
+	// Optional URL to navigate to when a new browser is warmed into the pool.
+	// Best-effort: failures to navigate do not fail pool fill. Only applied to
+	// newly-warmed browsers — browsers reused via release/acquire keep whatever URL
+	// the previous lease left them on. Accepts any URL Chromium can resolve, including
+	// chrome:// pages.
+	StartURL string `json:"start_url"`
 	// If true, launches the browser in stealth mode to reduce detection by anti-bot
 	// mechanisms.
 	Stealth bool `json:"stealth"`
@@ -226,6 +232,7 @@ type BrowserPoolBrowserPoolConfig struct {
 		Name              respjson.Field
 		Profile           respjson.Field
 		ProxyID           respjson.Field
+		StartURL          respjson.Field
 		Stealth           respjson.Field
 		TimeoutSeconds    respjson.Field
 		Viewport          respjson.Field
@@ -277,6 +284,9 @@ type BrowserPoolAcquireResponse struct {
 	Profile Profile `json:"profile"`
 	// ID of the proxy associated with this browser session, if any.
 	ProxyID string `json:"proxy_id"`
+	// URL the session was asked to navigate to on creation, if any. Recorded for
+	// debugging — navigation is best-effort and may have failed.
+	StartURL string `json:"start_url"`
 	// Session usage metrics.
 	Usage BrowserUsage `json:"usage"`
 	// Initial browser window size in pixels with optional refresh rate. If omitted,
@@ -310,6 +320,7 @@ type BrowserPoolAcquireResponse struct {
 		Pool               respjson.Field
 		Profile            respjson.Field
 		ProxyID            respjson.Field
+		StartURL           respjson.Field
 		Usage              respjson.Field
 		Viewport           respjson.Field
 		ExtraFields        map[string]respjson.Field
@@ -340,6 +351,12 @@ type BrowserPoolNewParams struct {
 	// Optional proxy to associate to the browser session. Must reference a proxy
 	// belonging to the caller's org.
 	ProxyID param.Opt[string] `json:"proxy_id,omitzero"`
+	// Optional URL to navigate to when a new browser is warmed into the pool.
+	// Best-effort: failures to navigate do not fail pool fill. Only applied to
+	// newly-warmed browsers — browsers reused via release/acquire keep whatever URL
+	// the previous lease left them on. Accepts any URL Chromium can resolve, including
+	// chrome:// pages.
+	StartURL param.Opt[string] `json:"start_url,omitzero"`
 	// If true, launches the browser in stealth mode to reduce detection by anti-bot
 	// mechanisms.
 	Stealth param.Opt[bool] `json:"stealth,omitzero"`
@@ -401,6 +418,12 @@ type BrowserPoolUpdateParams struct {
 	// Optional proxy to associate to the browser session. Must reference a proxy
 	// belonging to the caller's org.
 	ProxyID param.Opt[string] `json:"proxy_id,omitzero"`
+	// Optional URL to navigate to when a new browser is warmed into the pool.
+	// Best-effort: failures to navigate do not fail pool fill. Only applied to
+	// newly-warmed browsers — browsers reused via release/acquire keep whatever URL
+	// the previous lease left them on. Accepts any URL Chromium can resolve, including
+	// chrome:// pages.
+	StartURL param.Opt[string] `json:"start_url,omitzero"`
 	// If true, launches the browser in stealth mode to reduce detection by anti-bot
 	// mechanisms.
 	Stealth param.Opt[bool] `json:"stealth,omitzero"`

browserpool_test.go

@@ -46,6 +46,7 @@ func TestBrowserPoolNewWithOptionalParams(t *testing.T) {
 			SaveChanges: kernel.Bool(true),
 		},
 		ProxyID:        kernel.String("proxy_id"),
+		StartURL:       kernel.String("https://example.com"),
 		Stealth:        kernel.Bool(true),
 		TimeoutSeconds: kernel.Int(60),
 		Viewport: shared.BrowserViewportParam{
@@ -122,6 +123,7 @@ func TestBrowserPoolUpdateWithOptionalParams(t *testing.T) {
 				SaveChanges: kernel.Bool(true),
 			},
 			ProxyID:        kernel.String("proxy_id"),
+			StartURL:       kernel.String("https://example.com"),
 			Stealth:        kernel.Bool(true),
 			TimeoutSeconds: kernel.Int(60),
 			Viewport: shared.BrowserViewportParam{

invocation.go

@@ -574,6 +574,9 @@ type InvocationListBrowsersResponseBrowser struct {
 	Profile Profile `json:"profile"`
 	// ID of the proxy associated with this browser session, if any.
 	ProxyID string `json:"proxy_id"`
+	// URL the session was asked to navigate to on creation, if any. Recorded for
+	// debugging — navigation is best-effort and may have failed.
+	StartURL string `json:"start_url"`
 	// Session usage metrics.
 	Usage BrowserUsage `json:"usage"`
 	// Initial browser window size in pixels with optional refresh rate. If omitted,
@@ -607,6 +610,7 @@ type InvocationListBrowsersResponseBrowser struct {
 		Pool               respjson.Field
 		Profile            respjson.Field
 		ProxyID            respjson.Field
+		StartURL           respjson.Field
 		Usage              respjson.Field
 		Viewport           respjson.Field
 		ExtraFields        map[string]respjson.Field