@onkernel/sdk 0.55.0 → 0.58.0

package/src/client.ts

@@ -19,6 +19,15 @@ import { AbstractPage, type OffsetPaginationParams, OffsetPaginationResponse } f
 import * as Uploads from './core/uploads';
 import * as API from './resources/index';
 import { APIPromise } from './core/api-promise';
+import {
+  APIKey,
+  APIKeyCreateParams,
+  APIKeyListParams,
+  APIKeyUpdateParams,
+  APIKeys,
+  APIKeysOffsetPagination,
+  CreatedAPIKey,
+} from './resources/api-keys';
 import { AppListParams, AppListResponse, AppListResponsesOffsetPagination, Apps } from './resources/apps';
 import {
   BrowserRouteCache,
@@ -110,12 +119,10 @@ import {
   BrowserCreateResponse,
   BrowserCurlParams,
   BrowserCurlResponse,
-  BrowserDeleteParams,
   BrowserListParams,
   BrowserListResponse,
   BrowserListResponsesOffsetPagination,
   BrowserLoadExtensionsParams,
-  BrowserPersistence,
   BrowserPoolRef,
   BrowserRetrieveParams,
   BrowserRetrieveResponse,
@@ -972,6 +979,10 @@ export class Kernel {
    * Create and manage projects for resource isolation within an organization.
    */
   projects: API.Projects = new API.Projects(this);
+  /**
+   * Create and manage API keys for organization and project-scoped access.
+   */
+  apiKeys: API.APIKeys = new API.APIKeys(this);
   /**
    * Configure external credential providers like 1Password.
    */
@@ -989,6 +1000,7 @@ Kernel.Extensions = Extensions;
 Kernel.BrowserPools = BrowserPools;
 Kernel.Credentials = Credentials;
 Kernel.Projects = Projects;
+Kernel.APIKeys = APIKeys;
 Kernel.CredentialProviders = CredentialProviders;
 
 export declare namespace Kernel {
@@ -1038,7 +1050,6 @@ export declare namespace Kernel {
 
   export {
     Browsers as Browsers,
-    type BrowserPersistence as BrowserPersistence,
     type BrowserPoolRef as BrowserPoolRef,
     type BrowserUsage as BrowserUsage,
     type Profile as Profile,
@@ -1052,7 +1063,6 @@ export declare namespace Kernel {
     type BrowserRetrieveParams as BrowserRetrieveParams,
     type BrowserUpdateParams as BrowserUpdateParams,
     type BrowserListParams as BrowserListParams,
-    type BrowserDeleteParams as BrowserDeleteParams,
     type BrowserCurlParams as BrowserCurlParams,
     type BrowserLoadExtensionsParams as BrowserLoadExtensionsParams,
   };
@@ -1118,6 +1128,16 @@ export declare namespace Kernel {
     type ProjectListParams as ProjectListParams,
   };
 
+  export {
+    APIKeys as APIKeys,
+    type APIKey as APIKey,
+    type CreatedAPIKey as CreatedAPIKey,
+    type APIKeysOffsetPagination as APIKeysOffsetPagination,
+    type APIKeyCreateParams as APIKeyCreateParams,
+    type APIKeyUpdateParams as APIKeyUpdateParams,
+    type APIKeyListParams as APIKeyListParams,
+  };
+
   export {
     CredentialProviders as CredentialProviders,
     type CreateCredentialProviderRequest as CreateCredentialProviderRequest,

package/src/resources/api-keys.ts

@@ -0,0 +1,195 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { OffsetPagination, type OffsetPaginationParams, PagePromise } from '../core/pagination';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+/**
+ * Create and manage API keys for organization and project-scoped access.
+ */
+export class APIKeys extends APIResource {
+  /**
+   * Create a new API key within the authenticated organization.
+   *
+   * @example
+   * ```ts
+   * const createdAPIKey = await client.apiKeys.create({
+   *   name: 'staging',
+   * });
+   * ```
+   */
+  create(body: APIKeyCreateParams, options?: RequestOptions): APIPromise<CreatedAPIKey> {
+    return this._client.post('/org/api_keys', { body, ...options });
+  }
+
+  /**
+   * Retrieve an API key by ID for the authenticated organization. API keys are
+   * masked.
+   *
+   * @example
+   * ```ts
+   * const apiKey = await client.apiKeys.retrieve('id');
+   * ```
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<APIKey> {
+    return this._client.get(path`/org/api_keys/${id}`, options);
+  }
+
+  /**
+   * Update an API key's name.
+   *
+   * @example
+   * ```ts
+   * const apiKey = await client.apiKeys.update('id', {
+   *   name: 'new-api-name',
+   * });
+   * ```
+   */
+  update(id: string, body: APIKeyUpdateParams, options?: RequestOptions): APIPromise<APIKey> {
+    return this._client.patch(path`/org/api_keys/${id}`, { body, ...options });
+  }
+
+  /**
+   * List API keys for the authenticated organization. API keys are masked.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const apiKey of client.apiKeys.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: APIKeyListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<APIKeysOffsetPagination, APIKey> {
+    return this._client.getAPIList('/org/api_keys', OffsetPagination<APIKey>, { query, ...options });
+  }
+
+  /**
+   * Delete an API key.
+   *
+   * @example
+   * ```ts
+   * await client.apiKeys.delete('id');
+   * ```
+   */
+  delete(id: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/org/api_keys/${id}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export type APIKeysOffsetPagination = OffsetPagination<APIKey>;
+
+export interface APIKey {
+  /**
+   * Unique API key identifier
+   */
+  id: string;
+
+  /**
+   * When the API key was created
+   */
+  created_at: string;
+
+  created_by: APIKey.CreatedBy;
+
+  /**
+   * When the API key expires
+   */
+  expires_at: string | null;
+
+  /**
+   * Masked version of the API key
+   */
+  masked_key: string;
+
+  /**
+   * API key name
+   */
+  name: string;
+
+  /**
+   * Project identifier for project-scoped API keys. Null means org-wide.
+   */
+  project_id: string | null;
+
+  /**
+   * Project name for project-scoped API keys. Null means the key is org-wide or the
+   * project name is unavailable.
+   */
+  project_name: string | null;
+}
+
+export namespace APIKey {
+  export interface CreatedBy {
+    /**
+     * Kernel user ID of the creator.
+     */
+    id: string;
+
+    /**
+     * Email address of the creator.
+     */
+    email: string;
+
+    /**
+     * Display name of the creator, if available.
+     */
+    name: string | null;
+  }
+}
+
+/**
+ * API key returned immediately after creation. Includes the plaintext key once.
+ */
+export interface CreatedAPIKey extends APIKey {
+  /**
+   * Plaintext API key. Only returned once when the key is created.
+   */
+  key: string;
+}
+
+export interface APIKeyCreateParams {
+  /**
+   * API key name (1-255 characters)
+   */
+  name: string;
+
+  /**
+   * Number of days until expiry, up to 3650. Use null for never.
+   */
+  days_to_expire?: number | null;
+
+  /**
+   * Unique project identifier
+   */
+  project_id?: string | null;
+}
+
+export interface APIKeyUpdateParams {
+  /**
+   * New API key name
+   */
+  name: string;
+}
+
+export interface APIKeyListParams extends OffsetPaginationParams {}
+
+export declare namespace APIKeys {
+  export {
+    type APIKey as APIKey,
+    type CreatedAPIKey as CreatedAPIKey,
+    type APIKeysOffsetPagination as APIKeysOffsetPagination,
+    type APIKeyCreateParams as APIKeyCreateParams,
+    type APIKeyUpdateParams as APIKeyUpdateParams,
+    type APIKeyListParams as APIKeyListParams,
+  };
+}

package/src/resources/auth/connections.ts

@@ -269,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:

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';
@@ -238,9 +239,11 @@ export namespace BrowserPool {
     proxy_id?: string;
 
     /**
-     * Optional URL to open when a browser is created for the pool. Navigation is
-     * best-effort, so navigation failures do not prevent the pool from filling. Reused
-     * browsers keep the page left by the previous lease.
+     * 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.
      */
     start_url?: string;
 
@@ -323,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.
    */
@@ -339,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.
    */
@@ -361,10 +365,19 @@ export interface BrowserPoolAcquireResponse {
   proxy_id?: string;
 
   /**
-   * Start URL requested for the session, if provided.
+   * URL the session was asked to navigate to on creation, if any. Recorded for
+   * 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.
    */
@@ -443,9 +456,11 @@ export interface BrowserPoolCreateParams {
   proxy_id?: string;
 
   /**
-   * Optional URL to open when a browser is created for the pool. Navigation is
-   * best-effort, so navigation failures do not prevent the pool from filling. Reused
-   * browsers keep the page left by the previous lease.
+   * 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.
    */
   start_url?: string;
 
@@ -540,9 +555,11 @@ export interface BrowserPoolUpdateParams {
   proxy_id?: string;
 
   /**
-   * Optional URL to open when a browser is created for the pool. Navigation is
-   * best-effort, so navigation failures do not prevent the pool from filling. Reused
-   * browsers keep the page left by the previous lease.
+   * 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.
    */
   start_url?: string;