diff --git a/api.md b/api.md index c9292971..99c71618 100644 --- a/api.md +++ b/api.md @@ -67,6 +67,9 @@ Methods: Types: - BrowserPoolRef +- BrowserProxy +- BrowserProxyConfig +- BrowserProxyMode - BrowserUsage - Profile - Tags @@ -277,6 +280,7 @@ Types: - LoginResponse - ManagedAuth +- ManagedAuthBrowserConfig - ManagedAuthCreateRequest - ManagedAuthTimelineEvent - ManagedAuthUpdateRequest diff --git a/src/client.ts b/src/client.ts index 1e9d0f3a..46bc52f8 100644 --- a/src/client.ts +++ b/src/client.ts @@ -154,6 +154,9 @@ import { BrowserListResponsesOffsetPagination, BrowserLoadExtensionsParams, BrowserPoolRef, + BrowserProxy, + BrowserProxyConfig, + BrowserProxyMode, BrowserRetrieveParams, BrowserRetrieveResponse, BrowserUpdateParams, @@ -1113,6 +1116,9 @@ export declare namespace Kernel { export { Browsers as Browsers, type BrowserPoolRef as BrowserPoolRef, + type BrowserProxy as BrowserProxy, + type BrowserProxyConfig as BrowserProxyConfig, + type BrowserProxyMode as BrowserProxyMode, type BrowserUsage as BrowserUsage, type Profile as Profile, type Tags as Tags, diff --git a/src/resources/auth/auth.ts b/src/resources/auth/auth.ts index 945723a8..817d1201 100644 --- a/src/resources/auth/auth.ts +++ b/src/resources/auth/auth.ts @@ -13,6 +13,7 @@ import { Connections, LoginResponse, ManagedAuth, + ManagedAuthBrowserConfig, ManagedAuthCreateRequest, ManagedAuthTimelineEvent, ManagedAuthTimelineEventsOffsetPagination, @@ -39,6 +40,7 @@ export declare namespace Auth { Connections as Connections, type LoginResponse as LoginResponse, type ManagedAuth as ManagedAuth, + type ManagedAuthBrowserConfig as ManagedAuthBrowserConfig, type ManagedAuthCreateRequest as ManagedAuthCreateRequest, type ManagedAuthTimelineEvent as ManagedAuthTimelineEvent, type ManagedAuthUpdateRequest as ManagedAuthUpdateRequest, diff --git a/src/resources/auth/connections.ts b/src/resources/auth/connections.ts index b4ac01ca..30cb2805 100644 --- a/src/resources/auth/connections.ts +++ b/src/resources/auth/connections.ts @@ -2,6 +2,7 @@ import { APIResource } from '../../core/resource'; import * as Shared from '../shared'; +import * as BrowsersAPI from '../browsers/browsers'; import * as TelemetryAPI from '../browsers/telemetry'; import { APIPromise } from '../../core/api-promise'; import { OffsetPagination, type OffsetPaginationParams, PagePromise } from '../../core/pagination'; @@ -291,6 +292,12 @@ export interface ManagedAuth { */ auto_reauth?: boolean; + /** + * Default browser configuration for login, reauthentication, and health-check + * sessions. + */ + browser?: ManagedAuthBrowserConfig; + /** * ID of the underlying browser session driving the current flow (present when flow * in progress). Use this to inspect or terminate the browser session via the @@ -299,9 +306,8 @@ export interface ManagedAuth { browser_session_id?: string | null; /** - * Browser telemetry configuration used by this connection's browser sessions by - * default. The exact create-browser configuration is preserved and can be - * overridden per-login. + * @deprecated Deprecated. Use browser.telemetry. Retained during migration for + * existing clients. */ browser_telemetry?: ManagedAuth.BrowserTelemetry | null; @@ -343,6 +349,8 @@ export interface ManagedAuth { * automatically * - `requires_email_code` — flow needs an email code that cannot be received * automatically + * - `requires_customer_input` — flow needs another field or choice that is + * unavailable during unattended re-authentication */ can_reauth_reason?: | 'external_credential' @@ -358,7 +366,8 @@ export interface ManagedAuth { | 'requires_external_action' | 'requires_totp_without_secret' | 'requires_sms_code' - | 'requires_email_code'; + | 'requires_email_code' + | 'requires_customer_input'; /** * Canonical choices awaiting selection. Prefer this over pending_sso_buttons, @@ -435,9 +444,10 @@ export interface ManagedAuth { /** * Interval in seconds between automatic health checks. When set, the system * periodically verifies the authentication status and triggers re-authentication - * if needed. Maximum is 86400 (24 hours). Default is 3600 (1 hour). The minimum - * depends on your plan: Enterprise: 300 (5 minutes), Startup: 1200 (20 minutes), - * Hobbyist: 3600 (1 hour). + * if needed. Maximum is 86400 (24 hours). Default is 3600 (1 hour) or your plan + * minimum, whichever is larger. The minimum depends on your plan: Enterprise: 300 + * (5 minutes), Startup: 1200 (20 minutes), Hobbyist: 3600 (1 hour), Free: 21600 (6 + * hours). */ health_check_interval?: number | null; @@ -499,7 +509,8 @@ export interface ManagedAuth { post_login_url?: string; /** - * ID of the proxy associated with this connection, if any. + * @deprecated Deprecated. Read browser.proxy instead. Retained during migration + * for existing clients. */ proxy_id?: string; @@ -524,9 +535,8 @@ export interface ManagedAuth { export namespace ManagedAuth { /** - * Browser telemetry configuration used by this connection's browser sessions by - * default. The exact create-browser configuration is preserved and can be - * overridden per-login. + * @deprecated Deprecated. Use browser.telemetry. Retained during migration for + * existing clients. */ export interface BrowserTelemetry { /** @@ -835,6 +845,120 @@ export namespace ManagedAuth { } } +/** + * Browser configuration applied to browser sessions created for a managed auth + * connection. Managed auth controls the profile, headless mode, timeout, start + * URL, kiosk mode, and viewport. + */ +export interface ManagedAuthBrowserConfig { + /** + * Proxy configuration for managed auth browser sessions. Omit on create to derive + * the default from stealth, or on update and login to preserve or inherit the + * connection default. + */ + proxy?: BrowsersAPI.BrowserProxyConfig; + + /** + * Whether managed auth browser sessions use stealth mode. Defaults to true when + * omitted. + */ + stealth?: boolean; + + /** + * Browser telemetry configuration using the same semantics as browser create. + */ + telemetry?: ManagedAuthBrowserConfig.Telemetry | null; +} + +export namespace ManagedAuthBrowserConfig { + /** + * Browser telemetry configuration using the same semantics as browser create. + */ + export interface Telemetry { + /** + * Per-category capture flags. The operational categories (control, connection, + * system, captcha) are captured whenever telemetry is enabled; set one to + * enabled=false to opt out. The CDP categories (console, network, page, + * interaction) and screenshot are off by default; set enabled=true to opt in. On + * create, provided categories layer onto the default set. On update, provided + * categories merge onto the session's current config; when no telemetry is active + * this falls back to the default set (matching create). If browser is omitted or + * empty, the default set is used. A browser config that disables every category + * stops capture on update and starts no capture on create. + */ + browser?: TelemetryAPI.BrowserTelemetryCategoriesConfig; + + /** + * Request shortcut for browser telemetry capture. True enables capture; with no + * browser category settings it captures the default set (control, connection, + * system, captcha), and any browser category settings are layered onto that + * default set. On update, enabled=true resolves the config fresh from the default + * set plus any provided categories, replacing the session's current selection + * rather than merging onto it; omit enabled to merge categories onto the current + * selection instead. False stops capture on update and starts no capture on + * create. enabled=false cannot be combined with browser category settings. + */ + enabled?: boolean; + + /** + * Where to export this session's captured telemetry. Omit to capture without + * exporting. + */ + export?: Telemetry.Export; + } + + export namespace Telemetry { + /** + * Where to export this session's captured telemetry. Omit to capture without + * exporting. + */ + export interface Export { + /** + * Export captured telemetry over OTLP to one of the org's configured destinations. + */ + otlp?: Export.Otlp; + } + + export namespace Export { + /** + * Export captured telemetry over OTLP to one of the org's configured destinations. + */ + export interface Otlp { + /** + * OTLP destination to export this session's captured telemetry to. Provide either + * id or name. Requires telemetry capture to be enabled. + */ + destination?: Otlp.Destination; + + /** + * Whether to export captured telemetry over OTLP. Setting destination implies + * enabled=true, so this only needs to be set explicitly to disable export + * (enabled=false with a destination is rejected). + */ + enabled?: boolean; + } + + export namespace Otlp { + /** + * OTLP destination to export this session's captured telemetry to. Provide either + * id or name. Requires telemetry capture to be enabled. + */ + export interface Destination { + /** + * OTLP destination ID + */ + id?: string; + + /** + * OTLP destination name + */ + name?: string; + } + } + } + } +} + /** * Request to create an auth connection for a profile and domain */ @@ -884,9 +1008,14 @@ export interface ManagedAuthCreateRequest { auto_reauth?: boolean; /** - * Browser telemetry configuration used by this connection's browser sessions by - * default. Uses the exact create-browser configuration. Can be overridden - * per-login. + * Default browser configuration for login, reauthentication, and health-check + * sessions. + */ + browser?: ManagedAuthBrowserConfig; + + /** + * @deprecated Deprecated. Use browser.telemetry. Retained during migration for + * existing clients. */ browser_telemetry?: ManagedAuthCreateRequest.BrowserTelemetry | null; @@ -902,9 +1031,10 @@ export interface ManagedAuthCreateRequest { /** * Interval in seconds between automatic health checks. When set, the system * periodically verifies the authentication status and triggers re-authentication - * if needed. Maximum is 86400 (24 hours). Default is 3600 (1 hour). The minimum - * depends on your plan: Enterprise: 300 (5 minutes), Startup: 1200 (20 minutes), - * Hobbyist: 3600 (1 hour). + * if needed. Maximum is 86400 (24 hours). Default is 3600 (1 hour) or your plan + * minimum, whichever is larger. The minimum depends on your plan: Enterprise: 300 + * (5 minutes), Startup: 1200 (20 minutes), Hobbyist: 3600 (1 hour), Free: 21600 (6 + * hours). */ health_check_interval?: number; @@ -922,10 +1052,8 @@ export interface ManagedAuthCreateRequest { login_url?: string; /** - * Proxy selection. Provide either id or name. The proxy must be in the same - * project as the resource referencing it. When selecting by name, the name must - * match exactly one active proxy in the project. Ambiguous names return a 400; use - * id for stable references. + * @deprecated Deprecated. Use browser.proxy. Retained during migration for + * existing clients. */ proxy?: ManagedAuthCreateRequest.Proxy; @@ -944,9 +1072,8 @@ export interface ManagedAuthCreateRequest { export namespace ManagedAuthCreateRequest { /** - * Browser telemetry configuration used by this connection's browser sessions by - * default. Uses the exact create-browser configuration. Can be overridden - * per-login. + * @deprecated Deprecated. Use browser.telemetry. Retained during migration for + * existing clients. */ export interface BrowserTelemetry { /** @@ -1062,10 +1189,8 @@ export namespace ManagedAuthCreateRequest { } /** - * Proxy selection. Provide either id or name. The proxy must be in the same - * project as the resource referencing it. When selecting by name, the name must - * match exactly one active proxy in the project. Ambiguous names return a 400; use - * id for stable references. + * @deprecated Deprecated. Use browser.proxy. Retained during migration for + * existing clients. */ export interface Proxy { /** @@ -1186,9 +1311,14 @@ export interface ManagedAuthUpdateRequest { auto_reauth?: boolean; /** - * Browser telemetry configuration used by future browser sessions for this - * connection. Uses the exact create-browser configuration. Set enabled to false to - * disable telemetry. + * Browser configuration updates for future login, reauthentication, and + * health-check sessions. Omitted properties remain unchanged. + */ + browser?: ManagedAuthBrowserConfig; + + /** + * @deprecated Deprecated. Use browser.telemetry. Retained during migration for + * existing clients. */ browser_telemetry?: ManagedAuthUpdateRequest.BrowserTelemetry | null; @@ -1220,10 +1350,8 @@ export interface ManagedAuthUpdateRequest { login_url?: string; /** - * Proxy selection. Provide either id or name. The proxy must be in the same - * project as the resource referencing it. When selecting by name, the name must - * match exactly one active proxy in the project. Ambiguous names return a 400; use - * id for stable references. + * @deprecated Deprecated. Use browser.proxy. Retained during migration for + * existing clients. */ proxy?: ManagedAuthUpdateRequest.Proxy; @@ -1240,9 +1368,8 @@ export interface ManagedAuthUpdateRequest { export namespace ManagedAuthUpdateRequest { /** - * Browser telemetry configuration used by future browser sessions for this - * connection. Uses the exact create-browser configuration. Set enabled to false to - * disable telemetry. + * @deprecated Deprecated. Use browser.telemetry. Retained during migration for + * existing clients. */ export interface BrowserTelemetry { /** @@ -1358,10 +1485,8 @@ export namespace ManagedAuthUpdateRequest { } /** - * Proxy selection. Provide either id or name. The proxy must be in the same - * project as the resource referencing it. When selecting by name, the name must - * match exactly one active proxy in the project. Ambiguous names return a 400; use - * id for stable references. + * @deprecated Deprecated. Use browser.proxy. Retained during migration for + * existing clients. */ export interface Proxy { /** @@ -1787,9 +1912,14 @@ export interface ConnectionCreateParams { auto_reauth?: boolean; /** - * Browser telemetry configuration used by this connection's browser sessions by - * default. Uses the exact create-browser configuration. Can be overridden - * per-login. + * Default browser configuration for login, reauthentication, and health-check + * sessions. + */ + browser?: ManagedAuthBrowserConfig; + + /** + * @deprecated Deprecated. Use browser.telemetry. Retained during migration for + * existing clients. */ browser_telemetry?: ConnectionCreateParams.BrowserTelemetry | null; @@ -1805,9 +1935,10 @@ export interface ConnectionCreateParams { /** * Interval in seconds between automatic health checks. When set, the system * periodically verifies the authentication status and triggers re-authentication - * if needed. Maximum is 86400 (24 hours). Default is 3600 (1 hour). The minimum - * depends on your plan: Enterprise: 300 (5 minutes), Startup: 1200 (20 minutes), - * Hobbyist: 3600 (1 hour). + * if needed. Maximum is 86400 (24 hours). Default is 3600 (1 hour) or your plan + * minimum, whichever is larger. The minimum depends on your plan: Enterprise: 300 + * (5 minutes), Startup: 1200 (20 minutes), Hobbyist: 3600 (1 hour), Free: 21600 (6 + * hours). */ health_check_interval?: number; @@ -1825,10 +1956,8 @@ export interface ConnectionCreateParams { login_url?: string; /** - * Proxy selection. Provide either id or name. The proxy must be in the same - * project as the resource referencing it. When selecting by name, the name must - * match exactly one active proxy in the project. Ambiguous names return a 400; use - * id for stable references. + * @deprecated Deprecated. Use browser.proxy. Retained during migration for + * existing clients. */ proxy?: ConnectionCreateParams.Proxy; @@ -1847,9 +1976,8 @@ export interface ConnectionCreateParams { export namespace ConnectionCreateParams { /** - * Browser telemetry configuration used by this connection's browser sessions by - * default. Uses the exact create-browser configuration. Can be overridden - * per-login. + * @deprecated Deprecated. Use browser.telemetry. Retained during migration for + * existing clients. */ export interface BrowserTelemetry { /** @@ -1965,10 +2093,8 @@ export namespace ConnectionCreateParams { } /** - * Proxy selection. Provide either id or name. The proxy must be in the same - * project as the resource referencing it. When selecting by name, the name must - * match exactly one active proxy in the project. Ambiguous names return a 400; use - * id for stable references. + * @deprecated Deprecated. Use browser.proxy. Retained during migration for + * existing clients. */ export interface Proxy { /** @@ -2001,9 +2127,14 @@ export interface ConnectionUpdateParams { auto_reauth?: boolean; /** - * Browser telemetry configuration used by future browser sessions for this - * connection. Uses the exact create-browser configuration. Set enabled to false to - * disable telemetry. + * Browser configuration updates for future login, reauthentication, and + * health-check sessions. Omitted properties remain unchanged. + */ + browser?: ManagedAuthBrowserConfig; + + /** + * @deprecated Deprecated. Use browser.telemetry. Retained during migration for + * existing clients. */ browser_telemetry?: ConnectionUpdateParams.BrowserTelemetry | null; @@ -2035,10 +2166,8 @@ export interface ConnectionUpdateParams { login_url?: string; /** - * Proxy selection. Provide either id or name. The proxy must be in the same - * project as the resource referencing it. When selecting by name, the name must - * match exactly one active proxy in the project. Ambiguous names return a 400; use - * id for stable references. + * @deprecated Deprecated. Use browser.proxy. Retained during migration for + * existing clients. */ proxy?: ConnectionUpdateParams.Proxy; @@ -2055,9 +2184,8 @@ export interface ConnectionUpdateParams { export namespace ConnectionUpdateParams { /** - * Browser telemetry configuration used by future browser sessions for this - * connection. Uses the exact create-browser configuration. Set enabled to false to - * disable telemetry. + * @deprecated Deprecated. Use browser.telemetry. Retained during migration for + * existing clients. */ export interface BrowserTelemetry { /** @@ -2173,10 +2301,8 @@ export namespace ConnectionUpdateParams { } /** - * Proxy selection. Provide either id or name. The proxy must be in the same - * project as the resource referencing it. When selecting by name, the name must - * match exactly one active proxy in the project. Ambiguous names return a 400; use - * id for stable references. + * @deprecated Deprecated. Use browser.proxy. Retained during migration for + * existing clients. */ export interface Proxy { /** @@ -2210,17 +2336,20 @@ export interface ConnectionListParams extends OffsetPaginationParams { export interface ConnectionLoginParams { /** - * Override the connection's default browser telemetry configuration for this - * login. When omitted, the connection's browser_telemetry default is used. Uses - * the exact create-browser configuration. + * Browser configuration override for this login. Omitted properties inherit the + * connection defaults. + */ + browser?: ManagedAuthBrowserConfig; + + /** + * @deprecated Deprecated. Use browser.telemetry. Retained during migration for + * existing clients. */ browser_telemetry?: ConnectionLoginParams.BrowserTelemetry | null; /** - * Proxy selection. Provide either id or name. The proxy must be in the same - * project as the resource referencing it. When selecting by name, the name must - * match exactly one active proxy in the project. Ambiguous names return a 400; use - * id for stable references. + * @deprecated Deprecated. Use browser.proxy. Retained during migration for + * existing clients. */ proxy?: ConnectionLoginParams.Proxy; @@ -2233,9 +2362,8 @@ export interface ConnectionLoginParams { export namespace ConnectionLoginParams { /** - * Override the connection's default browser telemetry configuration for this - * login. When omitted, the connection's browser_telemetry default is used. Uses - * the exact create-browser configuration. + * @deprecated Deprecated. Use browser.telemetry. Retained during migration for + * existing clients. */ export interface BrowserTelemetry { /** @@ -2322,10 +2450,8 @@ export namespace ConnectionLoginParams { } /** - * Proxy selection. Provide either id or name. The proxy must be in the same - * project as the resource referencing it. When selecting by name, the name must - * match exactly one active proxy in the project. Ambiguous names return a 400; use - * id for stable references. + * @deprecated Deprecated. Use browser.proxy. Retained during migration for + * existing clients. */ export interface Proxy { /** @@ -2390,6 +2516,7 @@ export declare namespace Connections { export { type LoginResponse as LoginResponse, type ManagedAuth as ManagedAuth, + type ManagedAuthBrowserConfig as ManagedAuthBrowserConfig, type ManagedAuthCreateRequest as ManagedAuthCreateRequest, type ManagedAuthTimelineEvent as ManagedAuthTimelineEvent, type ManagedAuthUpdateRequest as ManagedAuthUpdateRequest, diff --git a/src/resources/auth/index.ts b/src/resources/auth/index.ts index 38494a56..ffe55c6e 100644 --- a/src/resources/auth/index.ts +++ b/src/resources/auth/index.ts @@ -5,6 +5,7 @@ export { Connections, type LoginResponse, type ManagedAuth, + type ManagedAuthBrowserConfig, type ManagedAuthCreateRequest, type ManagedAuthTimelineEvent, type ManagedAuthUpdateRequest, diff --git a/src/resources/browser-pools.ts b/src/resources/browser-pools.ts index d3de6c55..63567920 100644 --- a/src/resources/browser-pools.ts +++ b/src/resources/browser-pools.ts @@ -439,7 +439,13 @@ export interface BrowserPoolAcquireResponse { profile_save_changes?: boolean; /** - * ID of the proxy associated with this browser session, if any. + * Resolved proxy configuration for this browser session. + */ + proxy?: BrowsersAPI.BrowserProxy; + + /** + * @deprecated ID of the proxy associated with this browser session, if any. + * Deprecated in favor of proxy. */ proxy_id?: string; diff --git a/src/resources/browsers/browsers.ts b/src/resources/browsers/browsers.ts index 6520400a..72768485 100644 --- a/src/resources/browsers/browsers.ts +++ b/src/resources/browsers/browsers.ts @@ -296,6 +296,72 @@ export interface BrowserPoolRef { name?: string; } +/** + * Resolved proxy configuration for a browser session. Selected proxies are + * returned by stable ID. + */ +export interface BrowserProxy { + /** + * Selected proxy ID. + */ + id?: string; + + /** + * Proxy egress mode. direct forces no proxy regardless of stealth. default uses + * the browser's stealth-derived default: Kernel's default stealth proxy when + * stealth=true, or direct egress when stealth=false. default is primarily useful + * on browser update to restore the browser default after selected-proxy egress. + */ + mode?: BrowserProxyMode; + + /** + * Selected proxy name. + */ + name?: string; +} + +/** + * Browser proxy configuration. Provide exactly one of mode, id, or name; an empty + * object is invalid. Set mode to direct for no proxy regardless of stealth. Set + * mode to default to use the browser's stealth-derived default: Kernel's default + * stealth proxy when stealth=true, or direct egress when stealth=false. Select id + * or name to use that proxy regardless of stealth. The selected proxy must be in + * the same project as the browser. Names must match exactly one active proxy; use + * id for stable references. Proxy configuration changes only egress and does not + * change stealth or CAPTCHA solver behavior. A stealth browser using mode=direct + * still runs in stealth mode with the CAPTCHA solver enabled. When proxy is + * omitted on browser creation, stealth browsers use Kernel's default stealth proxy + * and non-stealth browsers use direct egress. When omitted on update, the current + * configuration is unchanged. + */ +export interface BrowserProxyConfig { + /** + * Proxy ID. + */ + id?: string; + + /** + * Proxy egress mode. direct forces no proxy regardless of stealth. default uses + * the browser's stealth-derived default: Kernel's default stealth proxy when + * stealth=true, or direct egress when stealth=false. default is primarily useful + * on browser update to restore the browser default after selected-proxy egress. + */ + mode?: BrowserProxyMode; + + /** + * Proxy name. Must match exactly one active proxy in the project. + */ + name?: string; +} + +/** + * Proxy egress mode. direct forces no proxy regardless of stealth. default uses + * the browser's stealth-derived default: Kernel's default stealth proxy when + * stealth=true, or direct egress when stealth=false. default is primarily useful + * on browser update to restore the browser default after selected-proxy egress. + */ +export type BrowserProxyMode = 'direct' | 'default'; + /** * Session usage metrics. */ @@ -433,7 +499,13 @@ export interface BrowserCreateResponse { profile_save_changes?: boolean; /** - * ID of the proxy associated with this browser session, if any. + * Resolved proxy configuration for this browser session. + */ + proxy?: BrowserProxy; + + /** + * @deprecated ID of the proxy associated with this browser session, if any. + * Deprecated in favor of proxy. */ proxy_id?: string; @@ -571,7 +643,13 @@ export interface BrowserRetrieveResponse { profile_save_changes?: boolean; /** - * ID of the proxy associated with this browser session, if any. + * Resolved proxy configuration for this browser session. + */ + proxy?: BrowserProxy; + + /** + * @deprecated ID of the proxy associated with this browser session, if any. + * Deprecated in favor of proxy. */ proxy_id?: string; @@ -709,7 +787,13 @@ export interface BrowserUpdateResponse { profile_save_changes?: boolean; /** - * ID of the proxy associated with this browser session, if any. + * Resolved proxy configuration for this browser session. + */ + proxy?: BrowserProxy; + + /** + * @deprecated ID of the proxy associated with this browser session, if any. + * Deprecated in favor of proxy. */ proxy_id?: string; @@ -847,7 +931,13 @@ export interface BrowserListResponse { profile_save_changes?: boolean; /** - * ID of the proxy associated with this browser session, if any. + * Resolved proxy configuration for this browser session. + */ + proxy?: BrowserProxy; + + /** + * @deprecated ID of the proxy associated with this browser session, if any. + * Deprecated in favor of proxy. */ proxy_id?: string; @@ -970,8 +1060,19 @@ export interface BrowserCreateParams { profile?: Shared.BrowserProfile; /** - * Optional proxy to associate to the browser session. Must reference a proxy in - * the same project as the browser session. + * Proxy configuration for the browser session. Cannot be combined with proxy_id. + * Omit to use the browser default: stealth browsers use Kernel's default stealth + * proxy, while non-stealth browsers use direct egress. Set mode to direct to force + * direct egress regardless of stealth. Set mode to default to explicitly use the + * browser default: Kernel's default stealth proxy when stealth=true, or direct + * egress when stealth=false. Select id or name to use that proxy regardless of + * stealth. Proxy selection does not change stealth or CAPTCHA solver behavior. + */ + proxy?: BrowserProxyConfig; + + /** + * @deprecated Optional proxy to associate to the browser session. Must reference a + * proxy in the same project as the browser session. Deprecated in favor of proxy. */ proxy_id?: string; @@ -983,8 +1084,11 @@ export interface BrowserCreateParams { start_url?: string; /** - * If true, launches the browser in stealth mode to reduce detection by anti-bot - * mechanisms. + * If true, launches the browser in stealth mode and enables the CAPTCHA solver. + * Defaults to false. When proxy is omitted, stealth browsers use Kernel's default + * stealth proxy and non-stealth browsers use direct egress. An explicit proxy + * configuration changes only egress; it does not enable or disable stealth or the + * CAPTCHA solver. */ stealth?: boolean; @@ -1132,8 +1236,8 @@ export interface BrowserRetrieveParams { export interface BrowserUpdateParams { /** - * If true, stealth browsers connect directly instead of using the default stealth - * proxy. + * @deprecated If true, stealth browsers connect directly instead of using the + * default stealth proxy. Deprecated in favor of proxy.mode. */ disable_default_proxy?: boolean; @@ -1151,8 +1255,18 @@ export interface BrowserUpdateParams { profile?: Shared.BrowserProfile; /** - * ID of the proxy to use. Omit to leave unchanged, set to empty string to remove - * proxy. + * Proxy configuration to apply. Omit to leave the current configuration unchanged. + * Cannot be combined with proxy_id or disable_default_proxy. Set mode to direct to + * switch to direct egress regardless of stealth. Set mode to default to restore + * the browser default after using a selected proxy: Kernel's default stealth proxy + * for a stealth browser, or direct egress for a non-stealth browser. Updating + * proxy does not change stealth or CAPTCHA solver behavior. + */ + proxy?: BrowserProxyConfig; + + /** + * @deprecated ID of the proxy to use. Omit to leave unchanged, set to empty string + * to remove proxy. Deprecated in favor of proxy. */ proxy_id?: string | null; @@ -1375,6 +1489,9 @@ Browsers.Playwright = Playwright; export declare namespace Browsers { export { type BrowserPoolRef as BrowserPoolRef, + type BrowserProxy as BrowserProxy, + type BrowserProxyConfig as BrowserProxyConfig, + type BrowserProxyMode as BrowserProxyMode, type BrowserUsage as BrowserUsage, type Profile as Profile, type Tags as Tags, diff --git a/src/resources/browsers/index.ts b/src/resources/browsers/index.ts index b11be82f..d589aa46 100644 --- a/src/resources/browsers/index.ts +++ b/src/resources/browsers/index.ts @@ -3,6 +3,9 @@ export { Browsers, type BrowserPoolRef, + type BrowserProxy, + type BrowserProxyConfig, + type BrowserProxyMode, type BrowserUsage, type Profile, type Tags, diff --git a/src/resources/index.ts b/src/resources/index.ts index dac7da9c..567202c9 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -41,6 +41,9 @@ export { export { Browsers, type BrowserPoolRef, + type BrowserProxy, + type BrowserProxyConfig, + type BrowserProxyMode, type BrowserUsage, type Profile, type Tags, diff --git a/src/resources/invocations.ts b/src/resources/invocations.ts index 02a051d6..77629231 100644 --- a/src/resources/invocations.ts +++ b/src/resources/invocations.ts @@ -510,7 +510,13 @@ export namespace InvocationListBrowsersResponse { profile_save_changes?: boolean; /** - * ID of the proxy associated with this browser session, if any. + * Resolved proxy configuration for this browser session. + */ + proxy?: BrowsersAPI.BrowserProxy; + + /** + * @deprecated ID of the proxy associated with this browser session, if any. + * Deprecated in favor of proxy. */ proxy_id?: string; diff --git a/tests/api-resources/auth/connections.test.ts b/tests/api-resources/auth/connections.test.ts index f3d0cf4e..94cad027 100644 --- a/tests/api-resources/auth/connections.test.ts +++ b/tests/api-resources/auth/connections.test.ts @@ -30,6 +30,34 @@ describe('resource connections', () => { profile_name: 'user-123', allowed_domains: ['login.netflix.com', 'auth.netflix.com'], auto_reauth: true, + browser: { + proxy: { + id: 'x', + mode: 'direct', + name: 'x', + }, + stealth: false, + telemetry: { + browser: { + captcha: { enabled: true }, + connection: { enabled: true }, + console: { enabled: true }, + control: { enabled: true }, + interaction: { enabled: true }, + network: { enabled: true }, + page: { enabled: true }, + screenshot: { enabled: true }, + system: { enabled: true }, + }, + enabled: true, + export: { + otlp: { + destination: { id: 'id', name: 'name' }, + enabled: true, + }, + }, + }, + }, browser_telemetry: { browser: { captcha: { enabled: true }, @@ -161,6 +189,34 @@ describe('resource connections', () => { client.auth.connections.login( 'id', { + browser: { + proxy: { + id: 'x', + mode: 'direct', + name: 'x', + }, + stealth: false, + telemetry: { + browser: { + captcha: { enabled: true }, + connection: { enabled: true }, + console: { enabled: true }, + control: { enabled: true }, + interaction: { enabled: true }, + network: { enabled: true }, + page: { enabled: true }, + screenshot: { enabled: true }, + system: { enabled: true }, + }, + enabled: true, + export: { + otlp: { + destination: { id: 'id', name: 'name' }, + enabled: true, + }, + }, + }, + }, browser_telemetry: { browser: { captcha: { enabled: true }, diff --git a/tests/api-resources/browsers/browsers.test.ts b/tests/api-resources/browsers/browsers.test.ts index 7521f5e2..a72f3f72 100644 --- a/tests/api-resources/browsers/browsers.test.ts +++ b/tests/api-resources/browsers/browsers.test.ts @@ -38,6 +38,11 @@ describe('resource browsers', () => { name: 'name', save_changes: true, }, + proxy: { + id: 'x', + mode: 'direct', + name: 'x', + }, proxy_id: 'proxy_id', start_url: 'https://example.com', stealth: true,