@onkernel/sdk 0.54.0 → 0.57.0

package/src/resources/auth/connections.ts

@@ -250,6 +250,17 @@ export interface ManagedAuth {
    */
   allowed_domains?: Array<string>;
 
+  /**
+   * Whether automatic re-authentication is permitted for this connection. This is an
+   * opt-in flag only — it does not check whether re-auth is actually feasible. Even
+   * when true, re-auth only runs when the system has what it needs to perform it
+   * (for example, saved credentials for the required login fields), and only after a
+   * scheduled health check detects an expired session — so this flag has no effect
+   * when `health_checks` is false. When false, expired sessions detected by a health
+   * check are marked as `NEEDS_AUTH` instead of attempting re-auth.
+   */
+  auto_reauth?: boolean;
+
   /**
    * 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
@@ -258,15 +269,59 @@ export interface ManagedAuth {
   browser_session_id?: string | null;
 
   /**
-   * Whether automatic re-authentication is possible (has credential, selectors, and
-   * login_url)
+   * Whether Kernel can automatically re-authenticate this connection when the
+   * session expires. Requires a prior successful login plus either a Kernel
+   * credential or an external credential reference. See `can_reauth_reason` for the
+   * specific outcome.
    */
   can_reauth?: boolean;
 
   /**
-   * Reason why automatic re-authentication is or is not possible
-   */
-  can_reauth_reason?: string;
+   * Machine-readable reason for the current value of `can_reauth`. Affirmative
+   * values (re-auth is possible):
+   *
+   * - `external_credential` — an external credential provider is attached
+   * - `cua_has_credential` — CUA flow with a stored credential
+   * - `has_credential` — Kernel credential is attached (optimistic; plan viability
+   *   not checked)
+   * - `viable_plans_found` — at least one stored login plan can be replayed
+   * - `no_requirements_recorded` — no recorded credential requirements to fail
+   *   against
+   * - `requirements_satisfiable` — recorded requirements can be met by the attached
+   *   credential
+   *
+   * Negative values (a human must complete the login flow):
+   *
+   * - `no_prior_successful_login` — connection has never completed a successful
+   *   login
+   * - `no_credential` — no Kernel or external credential attached
+   * - `no_viable_plans` — credential attached but no replayable login plan exists
+   *   yet
+   * - `viable_plans_require_external_action` — stored plans need an external step
+   *   (email link, push, etc.)
+   * - `requires_external_action` — recorded requirements include an external step
+   * - `requires_totp_without_secret` — flow needs a TOTP code but no TOTP secret is
+   *   stored
+   * - `requires_sms_code` — flow needs an SMS code that cannot be received
+   *   automatically
+   * - `requires_email_code` — flow needs an email code that cannot be received
+   *   automatically
+   */
+  can_reauth_reason?:
+    | 'external_credential'
+    | 'cua_has_credential'
+    | 'has_credential'
+    | 'viable_plans_found'
+    | 'no_requirements_recorded'
+    | 'requirements_satisfiable'
+    | 'no_prior_successful_login'
+    | 'no_credential'
+    | 'no_viable_plans'
+    | 'viable_plans_require_external_action'
+    | 'requires_external_action'
+    | 'requires_totp_without_secret'
+    | 'requires_sms_code'
+    | 'requires_email_code';
 
   /**
    * Reference to credentials for the auth connection. Use one of:
@@ -337,6 +392,15 @@ export interface ManagedAuth {
    */
   health_check_interval?: number | null;
 
+  /**
+   * Whether periodic health checks are enabled for this connection. When false, the
+   * system will not automatically verify authentication status, and `auto_reauth`
+   * has no effect on the automatic flow (since re-auth is only triggered by a failed
+   * scheduled health check). Manually triggering a health check via the API still
+   * works regardless of this setting.
+   */
+  health_checks?: boolean;
+
   /**
    * URL to redirect user to for hosted login (present when flow in progress)
    */
@@ -591,6 +655,18 @@ export interface ManagedAuthCreateRequest {
    */
   allowed_domains?: Array<string>;
 
+  /**
+   * Whether to permit automatic re-authentication when a scheduled health check
+   * detects an expired session. This is an opt-in flag only — it does not check
+   * whether re-auth is actually feasible. Even when true, re-auth only runs when the
+   * system has what it needs to perform it (for example, saved credentials for the
+   * required login fields), and only after a scheduled health check detects an
+   * expired session — so this flag has no effect when `health_checks` is false. When
+   * false, expired sessions are marked as `NEEDS_AUTH` instead of attempting
+   * re-auth. Defaults to true.
+   */
+  auto_reauth?: boolean;
+
   /**
    * Reference to credentials for the auth connection. Use one of:
    *
@@ -609,6 +685,14 @@ export interface ManagedAuthCreateRequest {
    */
   health_check_interval?: number;
 
+  /**
+   * Whether to enable periodic health checks. When false, the system will not
+   * automatically verify authentication status, and `auto_reauth` has no effect on
+   * the automatic flow (since re-auth is only triggered by a failed scheduled health
+   * check). Defaults to true.
+   */
+  health_checks?: boolean;
+
   /**
    * Optional login page URL to skip discovery
    */
@@ -689,6 +773,17 @@ export interface ManagedAuthUpdateRequest {
    */
   allowed_domains?: Array<string>;
 
+  /**
+   * Whether automatic re-authentication is permitted for this connection. This is an
+   * opt-in flag only — it does not check whether re-auth is actually feasible. Even
+   * when true, re-auth only runs when the system has what it needs to perform it
+   * (for example, saved credentials for the required login fields), and only after a
+   * scheduled health check detects an expired session — so this flag has no effect
+   * when `health_checks` is false. When false, expired sessions detected by a health
+   * check are marked as `NEEDS_AUTH` instead of attempting re-auth.
+   */
+  auto_reauth?: boolean;
+
   /**
    * Reference to credentials for the auth connection. Use one of:
    *
@@ -703,6 +798,14 @@ export interface ManagedAuthUpdateRequest {
    */
   health_check_interval?: number;
 
+  /**
+   * Whether periodic health checks are enabled. When set to false, the system will
+   * not automatically verify authentication status, and `auto_reauth` has no effect
+   * on the automatic flow (since re-auth is only triggered by a failed scheduled
+   * health check).
+   */
+  health_checks?: boolean;
+
   /**
    * Login page URL. Set to empty string to clear.
    */
@@ -1068,6 +1171,18 @@ export interface ConnectionCreateParams {
    */
   allowed_domains?: Array<string>;
 
+  /**
+   * Whether to permit automatic re-authentication when a scheduled health check
+   * detects an expired session. This is an opt-in flag only — it does not check
+   * whether re-auth is actually feasible. Even when true, re-auth only runs when the
+   * system has what it needs to perform it (for example, saved credentials for the
+   * required login fields), and only after a scheduled health check detects an
+   * expired session — so this flag has no effect when `health_checks` is false. When
+   * false, expired sessions are marked as `NEEDS_AUTH` instead of attempting
+   * re-auth. Defaults to true.
+   */
+  auto_reauth?: boolean;
+
   /**
    * Reference to credentials for the auth connection. Use one of:
    *
@@ -1086,6 +1201,14 @@ export interface ConnectionCreateParams {
    */
   health_check_interval?: number;
 
+  /**
+   * Whether to enable periodic health checks. When false, the system will not
+   * automatically verify authentication status, and `auto_reauth` has no effect on
+   * the automatic flow (since re-auth is only triggered by a failed scheduled health
+   * check). Defaults to true.
+   */
+  health_checks?: boolean;
+
   /**
    * Optional login page URL to skip discovery
    */
@@ -1163,6 +1286,17 @@ export interface ConnectionUpdateParams {
    */
   allowed_domains?: Array<string>;
 
+  /**
+   * Whether automatic re-authentication is permitted for this connection. This is an
+   * opt-in flag only — it does not check whether re-auth is actually feasible. Even
+   * when true, re-auth only runs when the system has what it needs to perform it
+   * (for example, saved credentials for the required login fields), and only after a
+   * scheduled health check detects an expired session — so this flag has no effect
+   * when `health_checks` is false. When false, expired sessions detected by a health
+   * check are marked as `NEEDS_AUTH` instead of attempting re-auth.
+   */
+  auto_reauth?: boolean;
+
   /**
    * Reference to credentials for the auth connection. Use one of:
    *
@@ -1177,6 +1311,14 @@ export interface ConnectionUpdateParams {
    */
   health_check_interval?: number;
 
+  /**
+   * Whether periodic health checks are enabled. When set to false, the system will
+   * not automatically verify authentication status, and `auto_reauth` has no effect
+   * on the automatic flow (since re-auth is only triggered by a failed scheduled
+   * health check).
+   */
+  health_checks?: boolean;
+
   /**
    * Login page URL. Set to empty string to clear.
    */

package/src/resources/browser-pools.ts

@@ -3,6 +3,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 { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
@@ -240,8 +241,8 @@ export namespace BrowserPool {
     /**
      * 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
+     * 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.
      */
     start_url?: string;
@@ -325,6 +326,13 @@ export interface BrowserPoolAcquireResponse {
    */
   browser_live_view_url?: string;
 
+  /**
+   * Custom Chrome enterprise policy overrides that were applied to this browser
+   * session, if any. Echoed back for verification. Keys are Chrome enterprise policy
+   * names.
+   */
+  chrome_policy?: { [key: string]: unknown };
+
   /**
    * When the browser session was soft-deleted. Only present for deleted sessions.
    */
@@ -341,12 +349,6 @@ export interface BrowserPoolAcquireResponse {
    */
   kiosk_mode?: boolean;
 
-  /**
-   * @deprecated DEPRECATED: Use timeout_seconds (up to 72 hours) and Profiles
-   * instead.
-   */
-  persistence?: BrowsersAPI.BrowserPersistence;
-
   /**
    * Browser pool this session was acquired from, if any.
    */
@@ -364,10 +366,18 @@ export interface BrowserPoolAcquireResponse {
 
   /**
    * URL the session was asked to navigate to on creation, if any. Recorded for
-   * debugging — navigation is best-effort and may have failed.
+   * debugging. Navigation is fire-and-forget — the URL is dispatched to the browser
+   * without waiting for it to load, and any errors (DNS failure, bad status,
+   * timeout) are silently dropped. Captures what was requested, not what the browser
+   * actually loaded.
    */
   start_url?: string;
 
+  /**
+   * Active telemetry configuration for the session, if any.
+   */
+  telemetry?: TelemetryAPI.BrowserTelemetryConfig | null;
+
   /**
    * Session usage metrics.
    */
@@ -448,8 +458,8 @@ export interface BrowserPoolCreateParams {
   /**
    * 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
+   * 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.
    */
   start_url?: string;
@@ -547,8 +557,8 @@ export interface BrowserPoolUpdateParams {
   /**
    * 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
+   * 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.
    */
   start_url?: string;