@onkernel/sdk 0.69.0 → 0.71.0

package/src/resources/auth/connections.ts

@@ -152,10 +152,39 @@ export class Connections extends APIResource {
   ): APIPromise<SubmitFieldsResponse> {
     return this._client.post(path`/auth/connections/${id}/submit`, { body, ...options });
   }
+
+  /**
+   * Returns a chronological timeline of events for an auth connection — login
+   * attempts, automatic re-auth attempts, and health checks. Events are returned
+   * newest-first.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const managedAuthTimelineEvent of client.auth.connections.timeline(
+   *   'id',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  timeline(
+    id: string,
+    query: ConnectionTimelineParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<ManagedAuthTimelineEventsOffsetPagination, ManagedAuthTimelineEvent> {
+    return this._client.getAPIList(
+      path`/auth/connections/${id}/timeline`,
+      OffsetPagination<ManagedAuthTimelineEvent>,
+      { query, ...options },
+    );
+  }
 }
 
 export type ManagedAuthsOffsetPagination = OffsetPagination<ManagedAuth>;
 
+export type ManagedAuthTimelineEventsOffsetPagination = OffsetPagination<ManagedAuthTimelineEvent>;
+
 /**
  * Response from starting a login flow
  */
@@ -764,6 +793,81 @@ export namespace ManagedAuthCreateRequest {
   }
 }
 
+/**
+ * A single event in an auth connection's history — a login attempt, an automatic
+ * re-auth attempt, or a health check.
+ */
+export interface ManagedAuthTimelineEvent {
+  /**
+   * Identifier of the underlying login/reauth session or health check.
+   */
+  id: string;
+
+  /**
+   * Outcome of the event. For login/reauth events this is the flow status
+   * (IN_PROGRESS, SUCCESS, EXPIRED, CANCELED, FAILED). For health_check events it is
+   * the observed session state (AUTHENTICATED, NEEDS_AUTH).
+   */
+  status: 'IN_PROGRESS' | 'SUCCESS' | 'EXPIRED' | 'CANCELED' | 'FAILED' | 'AUTHENTICATED' | 'NEEDS_AUTH';
+
+  /**
+   * When the event occurred.
+   */
+  timestamp: string;
+
+  /**
+   * The kind of event. "login" and "reauth" are authentication attempts;
+   * "health_check" is a periodic session-validity check.
+   */
+  type: 'login' | 'reauth' | 'health_check';
+
+  /**
+   * Machine-readable error code. Present when a login/reauth event failed.
+   */
+  error_code?: string;
+
+  /**
+   * Human-readable error message. Present when a login/reauth event failed.
+   */
+  error_message?: string;
+
+  /**
+   * The session state observed before this event. Present for health_check events
+   * that recorded a prior state.
+   */
+  previous_status?: 'AUTHENTICATED' | 'NEEDS_AUTH';
+
+  /**
+   * Replay recording ID for the event's browser session, if session recording was
+   * enabled.
+   */
+  replay_id?: string;
+
+  /**
+   * The step the flow reached. Present for login/reauth events.
+   */
+  step?:
+    | 'INITIALIZED'
+    | 'DISCOVERING'
+    | 'AWAITING_INPUT'
+    | 'AWAITING_EXTERNAL_ACTION'
+    | 'AWAITING_HUMAN_INTERVENTION'
+    | 'SUBMITTING'
+    | 'COMPLETED'
+    | 'EXPIRED';
+
+  /**
+   * When the event was last updated. Present for login/reauth events.
+   */
+  updated_at?: string;
+
+  /**
+   * Visible error message from the website (e.g., 'Incorrect password'). Present
+   * when the website displayed an error during the attempt.
+   */
+  website_error?: string;
+}
+
 /**
  * Request to update an auth connection's configuration
  */
@@ -1466,20 +1570,30 @@ export interface ConnectionSubmitParams {
   sso_provider?: string;
 }
 
+export interface ConnectionTimelineParams extends OffsetPaginationParams {
+  /**
+   * Filter the timeline to a single event type.
+   */
+  type?: 'login' | 'reauth' | 'health_check';
+}
+
 export declare namespace Connections {
   export {
     type LoginResponse as LoginResponse,
     type ManagedAuth as ManagedAuth,
     type ManagedAuthCreateRequest as ManagedAuthCreateRequest,
+    type ManagedAuthTimelineEvent as ManagedAuthTimelineEvent,
     type ManagedAuthUpdateRequest as ManagedAuthUpdateRequest,
     type SubmitFieldsRequest as SubmitFieldsRequest,
     type SubmitFieldsResponse as SubmitFieldsResponse,
     type ConnectionFollowResponse as ConnectionFollowResponse,
     type ManagedAuthsOffsetPagination as ManagedAuthsOffsetPagination,
+    type ManagedAuthTimelineEventsOffsetPagination as ManagedAuthTimelineEventsOffsetPagination,
     type ConnectionCreateParams as ConnectionCreateParams,
     type ConnectionUpdateParams as ConnectionUpdateParams,
     type ConnectionListParams as ConnectionListParams,
     type ConnectionLoginParams as ConnectionLoginParams,
     type ConnectionSubmitParams as ConnectionSubmitParams,
+    type ConnectionTimelineParams as ConnectionTimelineParams,
   };
 }

package/src/resources/auth/index.ts

@@ -6,6 +6,7 @@ export {
   type LoginResponse,
   type ManagedAuth,
   type ManagedAuthCreateRequest,
+  type ManagedAuthTimelineEvent,
   type ManagedAuthUpdateRequest,
   type SubmitFieldsRequest,
   type SubmitFieldsResponse,
@@ -15,5 +16,7 @@ export {
   type ConnectionListParams,
   type ConnectionLoginParams,
   type ConnectionSubmitParams,
+  type ConnectionTimelineParams,
   type ManagedAuthsOffsetPagination,
+  type ManagedAuthTimelineEventsOffsetPagination,
 } from './connections';

package/src/resources/browser-pools.ts

@@ -213,7 +213,9 @@ export namespace BrowserPool {
     extensions?: Array<Shared.BrowserExtension>;
 
     /**
-     * Percentage of the pool to fill per minute. Defaults to 10%.
+     * Percentage of the pool to fill per minute. Defaults to 10. The cap is 25 for
+     * most organizations but can be raised per-organization, so only the lower bound
+     * is enforced here.
      */
     fill_rate_per_minute?: number;
 
@@ -263,7 +265,7 @@ export namespace BrowserPool {
 
     /**
      * Default idle timeout in seconds for browsers acquired from this pool before they
-     * are destroyed. Defaults to 600 seconds if not specified
+     * are destroyed. Defaults to 600 seconds. Minimum 10, maximum 259200 (72 hours).
      */
     timeout_seconds?: number;
 
@@ -439,7 +441,9 @@ export interface BrowserPoolCreateParams {
   extensions?: Array<Shared.BrowserExtension>;
 
   /**
-   * Percentage of the pool to fill per minute. Defaults to 10%.
+   * Percentage of the pool to fill per minute. Defaults to 10. The cap is 25 for
+   * most organizations but can be raised per-organization, so only the lower bound
+   * is enforced here.
    */
   fill_rate_per_minute?: number;
 
@@ -489,7 +493,7 @@ export interface BrowserPoolCreateParams {
 
   /**
    * Default idle timeout in seconds for browsers acquired from this pool before they
-   * are destroyed. Defaults to 600 seconds if not specified
+   * are destroyed. Defaults to 600 seconds. Minimum 10, maximum 259200 (72 hours).
    */
   timeout_seconds?: number;
 
@@ -531,7 +535,9 @@ export interface BrowserPoolUpdateParams {
   extensions?: Array<Shared.BrowserExtension>;
 
   /**
-   * Percentage of the pool to fill per minute. Defaults to 10%.
+   * Percentage of the pool to fill per minute. Defaults to 10. The cap is 25 for
+   * most organizations but can be raised per-organization, so only the lower bound
+   * is enforced here.
    */
   fill_rate_per_minute?: number;
 
@@ -588,7 +594,7 @@ export interface BrowserPoolUpdateParams {
 
   /**
    * Default idle timeout in seconds for browsers acquired from this pool before they
-   * are destroyed. Defaults to 600 seconds if not specified
+   * are destroyed. Defaults to 600 seconds. Minimum 10, maximum 259200 (72 hours).
    */
   timeout_seconds?: number;
 
@@ -640,6 +646,13 @@ export interface BrowserPoolAcquireParams {
    */
   name?: string;
 
+  /**
+   * Optional URL to navigate the acquired browser to. Overrides the pool's start_url
+   * for this acquire only. Best-effort: failures to navigate do not fail the
+   * acquire.
+   */
+  start_url?: string;
+
   /**
    * Optional user-defined key-value tags for the acquired browser session, used to
    * find and group sessions later. Applies to this lease only and are cleared when

package/src/resources/browsers/browsers.ts

@@ -92,6 +92,9 @@ import {
   BrowserTelemetryConfig,
   BrowserTelemetryEvent,
   Telemetry as TelemetryAPITelemetry,
+  TelemetryEventsParams,
+  TelemetryEventsResponse,
+  TelemetryEventsResponsesOffsetPagination,
   TelemetryStreamParams,
   TelemetryStreamResponse,
 } from './telemetry';
@@ -1271,7 +1274,10 @@ export declare namespace Browsers {
     type BrowserTelemetryCategoryConfig as BrowserTelemetryCategoryConfig,
     type BrowserTelemetryConfig as BrowserTelemetryConfig,
     type BrowserTelemetryEvent as BrowserTelemetryEvent,
+    type TelemetryEventsResponse as TelemetryEventsResponse,
     type TelemetryStreamResponse as TelemetryStreamResponse,
+    type TelemetryEventsResponsesOffsetPagination as TelemetryEventsResponsesOffsetPagination,
+    type TelemetryEventsParams as TelemetryEventsParams,
     type TelemetryStreamParams as TelemetryStreamParams,
   };
 

package/src/resources/browsers/index.ts

@@ -120,6 +120,9 @@ export {
   type BrowserTelemetryCategoryConfig,
   type BrowserTelemetryConfig,
   type BrowserTelemetryEvent,
+  type TelemetryEventsResponse,
   type TelemetryStreamResponse,
+  type TelemetryEventsParams,
   type TelemetryStreamParams,
+  type TelemetryEventsResponsesOffsetPagination,
 } from './telemetry';

package/src/resources/browsers/telemetry.ts

@@ -3,6 +3,7 @@
 import { APIResource } from '../../core/resource';
 import * as TelemetryAPI from './telemetry';
 import { APIPromise } from '../../core/api-promise';
+import { OffsetPagination, type OffsetPaginationParams, PagePromise } from '../../core/pagination';
 import { Stream } from '../../core/streaming';
 import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
@@ -12,6 +13,34 @@ import { path } from '../../internal/utils/path';
  * Stream live telemetry events from a browser session.
  */
 export class Telemetry extends APIResource {
+  /**
+   * Reads a page of telemetry events for the browser session in ascending sequence
+   * order. To page through results, pass the X-Next-Offset value from the previous
+   * response as offset and repeat while X-Has-More is true. Returns an empty list
+   * when telemetry data is unavailable.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const telemetryEventsResponse of client.browsers.telemetry.events(
+   *   'id',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  events(
+    id: string,
+    query: TelemetryEventsParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<TelemetryEventsResponsesOffsetPagination, TelemetryEventsResponse> {
+    return this._client.getAPIList(
+      path`/browsers/${id}/telemetry/events`,
+      OffsetPagination<TelemetryEventsResponse>,
+      { query, ...options },
+    );
+  }
+
   /**
    * Streams browser telemetry events as a server-sent events (SSE) stream. The
    * stream closes when the browser session terminates. Each event frame includes an
@@ -20,7 +49,8 @@ export class Telemetry extends APIResource {
    * set; all frames carry JSON in the data: field. A keepalive comment frame is sent
    * every 15 seconds when no events arrive. Returns 404 if the browser session does
    * not exist. If telemetry was not enabled on the session, the stream opens but no
-   * events are delivered.
+   * events are delivered. Fresh connections only see new events; pass replay=all to
+   * start from the oldest retained event instead.
    *
    * @example
    * ```ts
@@ -34,8 +64,9 @@ export class Telemetry extends APIResource {
     params: TelemetryStreamParams | undefined = {},
     options?: RequestOptions,
   ): APIPromise<Stream<TelemetryStreamResponse>> {
-    const { 'Last-Event-ID': lastEventID } = params ?? {};
+    const { 'Last-Event-ID': lastEventID, ...query } = params ?? {};
     return this._client.get(path`/browsers/${id}/telemetry/stream`, {
+      query,
       ...options,
       headers: buildHeaders([
         {
@@ -49,6 +80,8 @@ export class Telemetry extends APIResource {
   }
 }
 
+export type TelemetryEventsResponsesOffsetPagination = OffsetPagination<TelemetryEventsResponse>;
+
 /**
  * An agent-driven HTTP call handled by the in-VM API server.
  */
@@ -1973,6 +2006,32 @@ export type BrowserTelemetryEvent =
   | BrowserSystemOomKillEvent
   | BrowserServiceCrashedEvent;
 
+/**
+ * Envelope wrapping a browser telemetry event with its monotonic sequence number.
+ * Each SSE data: frame carries one envelope as JSON. The seq value is also emitted
+ * as the SSE id: field so clients can pass it as Last-Event-ID on reconnect.
+ */
+export interface TelemetryEventsResponse {
+  /**
+   * Union type representing any browser telemetry event. Discriminated on `type`.
+   * Each event's `category` determines when it is captured. The CDP collector-health
+   * events (monitor_disconnected, monitor_reconnected, monitor_reconnect_failed,
+   * monitor_init_failed) use the `monitor` category, which is not user-configurable:
+   * it flows automatically whenever any CDP category (console, network, page,
+   * interaction) is captured, and is silent otherwise. monitor_screenshot uses the
+   * opt-in `screenshot` category. All other event types are controlled by their
+   * per-category enable/disable flags.
+   */
+  event: BrowserTelemetryEvent;
+
+  /**
+   * Process-monotonic sequence number assigned by the browser VM. Pass as
+   * Last-Event-ID on reconnect to resume without gaps. Gaps in received seq values
+   * indicate dropped events.
+   */
+  seq: number;
+}
+
 /**
  * Envelope wrapping a browser telemetry event with its monotonic sequence number.
  * Each SSE data: frame carries one envelope as JSON. The seq value is also emitted
@@ -1999,10 +2058,49 @@ export interface TelemetryStreamResponse {
   seq: number;
 }
 
+export interface TelemetryEventsParams extends OffsetPaginationParams {
+  /**
+   * Restrict results to these event categories. Repeat the parameter for multiple
+   * values.
+   */
+  category?: Array<
+    | 'console'
+    | 'network'
+    | 'page'
+    | 'interaction'
+    | 'control'
+    | 'connection'
+    | 'system'
+    | 'screenshot'
+    | 'captcha'
+    | 'monitor'
+  >;
+
+  /**
+   * Start of the window: an RFC-3339 timestamp, or a duration like 5m meaning that
+   * long ago. Defaults to 5m. Ignored when offset is set.
+   */
+  since?: string;
+
+  /**
+   * End of the window (exclusive): an RFC-3339 timestamp, or a duration like 5m
+   * meaning that long ago.
+   */
+  until?: string;
+}
+
 export interface TelemetryStreamParams {
   /**
-   * Last event sequence number for SSE reconnection (sent by SSE clients on
-   * reconnect)
+   * Query param: Pass `all` to start from the oldest retained event instead of only
+   * new events; any other value is treated as from-now. The buffer is bounded, so
+   * the first event id may be greater than 1 if older events were evicted.
+   */
+  replay?: string;
+
+  /**
+   * Header param: Last event sequence number for SSE reconnection (sent by SSE
+   * clients on reconnect). Takes precedence over replay when both are present, so
+   * reconnect resumes instead of re-replaying.
    */
   'Last-Event-ID'?: string;
 }
@@ -2047,7 +2145,10 @@ export declare namespace Telemetry {
     type BrowserTelemetryCategoryConfig as BrowserTelemetryCategoryConfig,
     type BrowserTelemetryConfig as BrowserTelemetryConfig,
     type BrowserTelemetryEvent as BrowserTelemetryEvent,
+    type TelemetryEventsResponse as TelemetryEventsResponse,
     type TelemetryStreamResponse as TelemetryStreamResponse,
+    type TelemetryEventsResponsesOffsetPagination as TelemetryEventsResponsesOffsetPagination,
+    type TelemetryEventsParams as TelemetryEventsParams,
     type TelemetryStreamParams as TelemetryStreamParams,
   };
 }

package/src/resources/extensions.ts

@@ -97,6 +97,19 @@ export class Extensions extends APIResource {
     });
   }
 
+  /**
+   * Get an extension's metadata (name, size, timestamps) by ID or name, without
+   * downloading the archive.
+   *
+   * @example
+   * ```ts
+   * const extension = await client.extensions.get('id_or_name');
+   * ```
+   */
+  get(idOrName: string, options?: RequestOptions): APIPromise<ExtensionGetResponse> {
+    return this._client.get(path`/extensions/${idOrName}/metadata`, options);
+  }
+
   /**
    * Upload a zip file containing an unpacked browser extension. Optionally provide a
    * unique name for later reference.
@@ -146,6 +159,37 @@ export interface ExtensionListResponse {
   name?: string | null;
 }
 
+/**
+ * A browser extension uploaded to Kernel.
+ */
+export interface ExtensionGetResponse {
+  /**
+   * Unique identifier for the extension
+   */
+  id: string;
+
+  /**
+   * Timestamp when the extension was created
+   */
+  created_at: string;
+
+  /**
+   * Size of the extension archive in bytes
+   */
+  size_bytes: number;
+
+  /**
+   * Timestamp when the extension was last used
+   */
+  last_used_at?: string | null;
+
+  /**
+   * Optional, easier-to-reference name for the extension. Must be unique within the
+   * project.
+   */
+  name?: string | null;
+}
+
 /**
  * A browser extension uploaded to Kernel.
  */
@@ -211,6 +255,7 @@ export interface ExtensionUploadParams {
 export declare namespace Extensions {
   export {
     type ExtensionListResponse as ExtensionListResponse,
+    type ExtensionGetResponse as ExtensionGetResponse,
     type ExtensionUploadResponse as ExtensionUploadResponse,
     type ExtensionListResponsesOffsetPagination as ExtensionListResponsesOffsetPagination,
     type ExtensionListParams as ExtensionListParams,

package/src/resources/index.ts

@@ -18,6 +18,12 @@ export {
   type AppListParams,
   type AppListResponsesOffsetPagination,
 } from './apps';
+export {
+  AuditLogs,
+  type AuditLogEntry,
+  type AuditLogListParams,
+  type AuditLogEntriesPageTokenPagination,
+} from './audit-logs';
 export { Auth } from './auth/auth';
 export {
   BrowserPools,
@@ -90,6 +96,7 @@ export {
 export {
   Extensions,
   type ExtensionListResponse,
+  type ExtensionGetResponse,
   type ExtensionUploadResponse,
   type ExtensionListParams,
   type ExtensionDownloadFromChromeStoreParams,

package/src/resources/projects/projects.ts

@@ -30,7 +30,7 @@ export class Projects extends APIResource {
   }
 
   /**
-   * Get a project by ID.
+   * Get a project by its ID or by its name. Names are unique within an organization.
    *
    * @example
    * ```ts

package/src/resources/shared.ts

@@ -79,18 +79,18 @@ export interface BrowserProfile {
  */
 export interface BrowserViewport {
   /**
-   * Browser window height in pixels.
+   * Browser window height in pixels. Any positive integer is accepted.
    */
   height: number;
 
   /**
-   * Browser window width in pixels.
+   * Browser window width in pixels. Any positive integer is accepted.
    */
   width: number;
 
   /**
-   * Display refresh rate in Hz. If omitted, automatically determined from width and
-   * height.
+   * Display refresh rate in Hz. Any positive integer is accepted; if omitted,
+   * automatically determined from width and height.
    */
   refresh_rate?: number;
 }

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.69.0'; // x-release-please-version
+export const VERSION = '0.71.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.69.0";
+export declare const VERSION = "0.71.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.69.0";
+export declare const VERSION = "0.71.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.69.0'; // x-release-please-version
+exports.VERSION = '0.71.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.69.0'; // x-release-please-version
+export const VERSION = '0.71.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map