@onkernel/sdk 0.95.0 → 0.97.0

package/src/resources/browsers/telemetry.ts

@@ -192,6 +192,99 @@ export namespace BrowserCallStack {
   }
 }
 
+/**
+ * A visible captcha challenge reached a terminal outcome.
+ */
+export interface BrowserCaptchaChallengeResultEvent {
+  category: 'captcha';
+
+  /**
+   * Per-challenge payload. This event is emitted once per challenge and determines
+   * its overall outcome; captcha_solve_started and captcha_solve_result describe
+   * individual tasks and may occur multiple times within the challenge.
+   */
+  data: BrowserCaptchaChallengeResultEvent.Data;
+
+  /**
+   * Provenance metadata identifying which producer emitted the event.
+   */
+  source: BrowserEventSource;
+
+  /**
+   * Event timestamp in Unix microseconds.
+   */
+  ts: number;
+
+  type: 'captcha_challenge_result';
+
+  /**
+   * True if the data field was truncated due to size limits.
+   */
+  truncated?: boolean;
+}
+
+export namespace BrowserCaptchaChallengeResultEvent {
+  /**
+   * Per-challenge payload. This event is emitted once per challenge and determines
+   * its overall outcome; captcha_solve_started and captcha_solve_result describe
+   * individual tasks and may occur multiple times within the challenge.
+   */
+  export interface Data {
+    /**
+     * Captcha kind. Enterprise reCAPTCHA variants are grouped into their version
+     * bucket (recaptcha_v2 or recaptcha_v3), press-and-hold challenges use
+     * press_and_hold, and unlisted kinds use other.
+     */
+    captcha_type:
+      | 'hcaptcha'
+      | 'recaptcha_v2'
+      | 'recaptcha_v3'
+      | 'turnstile'
+      | 'geetest'
+      | 'press_and_hold'
+      | 'other';
+
+    /**
+     * Opaque identifier shared by events for one visible challenge. An image-grid
+     * captcha may create multiple task_id values for one challenge_id. The same value
+     * may continue across a page reload when the challenge episode continues. It does
+     * not indicate task ordering or challenge completion.
+     */
+    challenge_id: string;
+
+    /**
+     * Wall-clock duration from the challenge appearing to its terminal outcome,
+     * covering every solver attempt in between.
+     */
+    duration_ms: number;
+
+    /**
+     * Terminal outcome of the visible challenge. solved: the page observed the
+     * challenge clear after a solver attempt. failure: a terminal solver failure
+     * occurred, or all attempts ended while the challenge remained. timeout: the
+     * challenge-level wait budget expired while the challenge remained. abandoned:
+     * observation ended without an attributable terminal challenge outcome. This
+     * includes a dismissed widget or page unload without a solved signal or terminal
+     * solver outcome, and a token appearing while multiple same-provider challenges
+     * are open, because the producer cannot attribute that token to this visible
+     * challenge. A captcha_solve_result with the same challenge_id may therefore
+     * report success while the challenge result reports abandoned. A solved challenge
+     * does not prove the site accepted the token or that the guarded action succeeded.
+     */
+    status: 'solved' | 'failure' | 'timeout' | 'abandoned';
+
+    /**
+     * Host of the page where the challenge appeared.
+     */
+    website_host?: string;
+
+    /**
+     * Path of the page where the challenge appeared. Query string excluded.
+     */
+    website_path?: string;
+  }
+}
+
 /**
  * A captcha solve attempt reached a terminal outcome.
  */
@@ -221,13 +314,23 @@ export interface BrowserCaptchaSolveResultEvent {
 export namespace BrowserCaptchaSolveResultEvent {
   export interface Data {
     /**
-     * Captcha vendor family. Provider-specific task names are normalized into this
-     * set; anything not covered is reported as other.
-     */
-    captcha_type: 'hcaptcha' | 'recaptcha_v2' | 'recaptcha_v3' | 'turnstile' | 'geetest' | 'other';
+     * Captcha kind. Enterprise reCAPTCHA variants are grouped into their version
+     * bucket (recaptcha_v2 or recaptcha_v3), press-and-hold challenges use
+     * press_and_hold, and unlisted kinds use other.
+     */
+    captcha_type:
+      | 'hcaptcha'
+      | 'recaptcha_v2'
+      | 'recaptcha_v3'
+      | 'turnstile'
+      | 'geetest'
+      | 'press_and_hold'
+      | 'other';
 
     /**
-     * Wall-clock duration from solve start to terminal outcome.
+     * Wall-clock duration from solve start to terminal outcome. Authoritative solve
+     * timing; do not derive it from the gap to a captcha_solve_started event, whose
+     * delivery and ordering are not guaranteed.
      */
     duration_ms: number;
 
@@ -239,6 +342,14 @@ export namespace BrowserCaptchaSolveResultEvent {
      */
     status: 'success' | 'failure' | 'timeout' | 'abandoned';
 
+    /**
+     * Opaque identifier shared by events for one visible challenge. An image-grid
+     * captcha may create multiple task_id values for one challenge_id. The same value
+     * may continue across a page reload when the challenge episode continues. It does
+     * not indicate task ordering or challenge completion.
+     */
+    challenge_id?: string;
+
     /**
      * Solver-specific error code on failure (e.g. ERROR_CAPTCHA_UNSOLVABLE). Absent on
      * success.
@@ -246,7 +357,7 @@ export namespace BrowserCaptchaSolveResultEvent {
     error_code?: string;
 
     /**
-     * Solver-assigned identifier. Opaque, useful for support cross-references.
+     * Opaque identifier shared with the matching captcha_solve_started.
      */
     task_id?: string;
 
@@ -262,6 +373,86 @@ export namespace BrowserCaptchaSolveResultEvent {
   }
 }
 
+/**
+ * A captcha solver accepted a task.
+ */
+export interface BrowserCaptchaSolveStartedEvent {
+  category: 'captcha';
+
+  /**
+   * Per-task payload. A visible challenge may create multiple tasks. When present,
+   * task_id correlates this event with a captcha_solve_result, while challenge_id
+   * groups tasks from the same challenge. Events may arrive out of order or be
+   * absent, so their arrival does not indicate current solve state.
+   */
+  data: BrowserCaptchaSolveStartedEvent.Data;
+
+  /**
+   * Provenance metadata identifying which producer emitted the event.
+   */
+  source: BrowserEventSource;
+
+  /**
+   * Event timestamp in Unix microseconds.
+   */
+  ts: number;
+
+  type: 'captcha_solve_started';
+
+  /**
+   * True if the data field was truncated due to size limits.
+   */
+  truncated?: boolean;
+}
+
+export namespace BrowserCaptchaSolveStartedEvent {
+  /**
+   * Per-task payload. A visible challenge may create multiple tasks. When present,
+   * task_id correlates this event with a captcha_solve_result, while challenge_id
+   * groups tasks from the same challenge. Events may arrive out of order or be
+   * absent, so their arrival does not indicate current solve state.
+   */
+  export interface Data {
+    /**
+     * Captcha kind. Enterprise reCAPTCHA variants are grouped into their version
+     * bucket (recaptcha_v2 or recaptcha_v3), press-and-hold challenges use
+     * press_and_hold, and unlisted kinds use other.
+     */
+    captcha_type:
+      | 'hcaptcha'
+      | 'recaptcha_v2'
+      | 'recaptcha_v3'
+      | 'turnstile'
+      | 'geetest'
+      | 'press_and_hold'
+      | 'other';
+
+    /**
+     * Opaque identifier shared by events for one visible challenge. An image-grid
+     * captcha may create multiple task_id values for one challenge_id. The same value
+     * may continue across a page reload when the challenge episode continues. It does
+     * not indicate task ordering or challenge completion.
+     */
+    challenge_id?: string;
+
+    /**
+     * Opaque identifier shared with the matching captcha_solve_result.
+     */
+    task_id?: string;
+
+    /**
+     * Host of the page where the captcha is being solved. May be empty for solver
+     * tasks that carry no page URL.
+     */
+    website_host?: string;
+
+    /**
+     * Path of the page where the captcha is being solved. Query string excluded.
+     */
+    website_path?: string;
+  }
+}
+
 /**
  * A browser-control command a client sent over the CDP WebSocket proxy: input
  * gestures, navigation, dialog handling, file selection and screenshots.
@@ -4346,7 +4537,7 @@ export namespace BrowserSystemOomKillEvent {
  */
 export interface BrowserTelemetryCategoriesConfig {
   /**
-   * Captcha solve attempt outcomes. On by default.
+   * Captcha solver tasks and visible challenge outcomes. On by default.
    */
   captcha?: BrowserTelemetryCategoryConfig;
 
@@ -4516,7 +4707,9 @@ export type BrowserTelemetryEvent =
   | BrowserCdpDisconnectEvent
   | BrowserLiveViewConnectEvent
   | BrowserLiveViewDisconnectEvent
+  | BrowserCaptchaSolveStartedEvent
   | BrowserCaptchaSolveResultEvent
+  | BrowserCaptchaChallengeResultEvent
   | BrowserSystemOomKillEvent
   | BrowserServiceCrashedEvent;
 
@@ -4660,7 +4853,9 @@ export declare namespace Telemetry {
   export {
     type BrowserAPICallEvent as BrowserAPICallEvent,
     type BrowserCallStack as BrowserCallStack,
+    type BrowserCaptchaChallengeResultEvent as BrowserCaptchaChallengeResultEvent,
     type BrowserCaptchaSolveResultEvent as BrowserCaptchaSolveResultEvent,
+    type BrowserCaptchaSolveStartedEvent as BrowserCaptchaSolveStartedEvent,
     type BrowserCdpCommandEvent as BrowserCdpCommandEvent,
     type BrowserCdpCommandMethod as BrowserCdpCommandMethod,
     type BrowserCdpConnectEvent as BrowserCdpConnectEvent,

package/src/resources/config-registry/analyses.ts

@@ -0,0 +1,63 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as ConfigRegistryAPI from './config-registry';
+import { AnalysisSummariesOffsetPagination } from './config-registry';
+import { APIPromise } from '../../core/api-promise';
+import { OffsetPagination, type OffsetPaginationParams, PagePromise } from '../../core/pagination';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Resolve browser and proxy recommendations for bot-protected sites.
+ */
+export class Analyses extends APIResource {
+  /**
+   * Returns a project-scoped historical analysis and the recommendation outcome
+   * concluded by that run. Later knowledge does not change this response.
+   *
+   * @example
+   * ```ts
+   * const configRegistryResponse =
+   *   await client.configRegistry.analyses.retrieve('id');
+   * ```
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<ConfigRegistryAPI.ConfigRegistryResponse> {
+    return this._client.get(path`/config-registry/analyses/${id}`, options);
+  }
+
+  /**
+   * Lists analyses for the selected project, newest first.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const analysisSummary of client.configRegistry.analyses.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: AnalysisListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<AnalysisSummariesOffsetPagination, ConfigRegistryAPI.AnalysisSummary> {
+    return this._client.getAPIList(
+      '/config-registry/analyses',
+      OffsetPagination<ConfigRegistryAPI.AnalysisSummary>,
+      { query, ...options },
+    );
+  }
+}
+
+export interface AnalysisListParams extends OffsetPaginationParams {
+  /**
+   * Case-insensitive substring search over requested URLs.
+   */
+  search?: string;
+}
+
+export declare namespace Analyses {
+  export { type AnalysisListParams as AnalysisListParams };
+}
+
+export { type AnalysisSummariesOffsetPagination };

package/src/resources/{site-configs.ts → config-registry/config-registry.ts}

@@ -1,47 +1,18 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../core/resource';
-import * as Shared from './shared';
-import { APIPromise } from '../core/api-promise';
-import { OffsetPagination, type OffsetPaginationParams, PagePromise } from '../core/pagination';
-import { RequestOptions } from '../internal/request-options';
-import { path } from '../internal/utils/path';
+import { APIResource } from '../../core/resource';
+import * as Shared from '../shared';
+import * as AnalysesAPI from './analyses';
+import { Analyses, AnalysisListParams } from './analyses';
+import { APIPromise } from '../../core/api-promise';
+import { OffsetPagination, type OffsetPaginationParams, PagePromise } from '../../core/pagination';
+import { RequestOptions } from '../../internal/request-options';
 
 /**
  * Resolve browser and proxy recommendations for bot-protected sites.
  */
-export class SiteConfigs extends APIResource {
-  /**
-   * Returns a project-scoped historical analysis and the recommendation outcome
-   * concluded by that run. Later knowledge does not change this response.
-   *
-   * @example
-   * ```ts
-   * const siteConfigResponse =
-   *   await client.siteConfigs.retrieve('id');
-   * ```
-   */
-  retrieve(id: string, options?: RequestOptions): APIPromise<SiteConfigResponse> {
-    return this._client.get(path`/site-configs/${id}`, options);
-  }
-
-  /**
-   * Lists analyses for the selected project, newest first.
-   *
-   * @example
-   * ```ts
-   * // Automatically fetches more pages as needed.
-   * for await (const analysisSummary of client.siteConfigs.list()) {
-   *   // ...
-   * }
-   * ```
-   */
-  list(
-    query: SiteConfigListParams | null | undefined = {},
-    options?: RequestOptions,
-  ): PagePromise<AnalysisSummariesOffsetPagination, AnalysisSummary> {
-    return this._client.getAPIList('/site-configs', OffsetPagination<AnalysisSummary>, { query, ...options });
-  }
+export class ConfigRegistry extends APIResource {
+  analyses: AnalysesAPI.Analyses = new AnalysesAPI.Analyses(this._client);
 
   /**
    * Lists unique domains previously analyzed by the selected project with their
@@ -50,16 +21,16 @@ export class SiteConfigs extends APIResource {
    * @example
    * ```ts
    * // Automatically fetches more pages as needed.
-   * for await (const recommendationSummary of client.siteConfigs.listRecommendations()) {
+   * for await (const recommendationSummary of client.configRegistry.list()) {
    *   // ...
    * }
    * ```
    */
-  listRecommendations(
-    query: SiteConfigListRecommendationsParams | null | undefined = {},
+  list(
+    query: ConfigRegistryListParams | null | undefined = {},
     options?: RequestOptions,
   ): PagePromise<RecommendationSummariesOffsetPagination, RecommendationSummary> {
-    return this._client.getAPIList('/site-configs/recommendations', OffsetPagination<RecommendationSummary>, {
+    return this._client.getAPIList('/config-registry', OffsetPagination<RecommendationSummary>, {
       query,
       ...options,
     });
@@ -67,40 +38,41 @@ export class SiteConfigs extends APIResource {
 
   /**
    * Returns current global knowledge without resolving DNS, creating an analysis, or
-   * updating Site Config data.
+   * updating config registry data.
    *
    * @example
    * ```ts
-   * const lookupResponse = await client.siteConfigs.lookup({
+   * const lookupResponse = await client.configRegistry.lookup({
    *   url: 'https://example.com',
    * });
    * ```
    */
-  lookup(body: SiteConfigLookupParams, options?: RequestOptions): APIPromise<LookupResponse> {
-    return this._client.post('/site-configs/lookup', { body, ...options });
+  lookup(body: ConfigRegistryLookupParams, options?: RequestOptions): APIPromise<LookupResponse> {
+    return this._client.post('/config-registry/lookup', { body, ...options });
   }
 
   /**
    * Explicitly starts or retries a project-scoped background analysis while
-   * preserving current global knowledge when available. Use `/site-configs/lookup`
-   * for side-effect-free reads.
+   * preserving current global knowledge when available. Use
+   * `/config-registry/lookup` for side-effect-free reads.
    *
    * @example
    * ```ts
-   * const siteConfigResponse = await client.siteConfigs.resolve(
-   *   { url: 'https://example.com' },
-   * );
+   * const configRegistryResponse =
+   *   await client.configRegistry.resolve({
+   *     url: 'https://example.com',
+   *   });
    * ```
    */
-  resolve(body: SiteConfigResolveParams, options?: RequestOptions): APIPromise<SiteConfigResponse> {
-    return this._client.post('/site-configs/resolve', { body, ...options });
+  resolve(body: ConfigRegistryResolveParams, options?: RequestOptions): APIPromise<ConfigRegistryResponse> {
+    return this._client.post('/config-registry/resolve', { body, ...options });
   }
 }
 
-export type AnalysisSummariesOffsetPagination = OffsetPagination<AnalysisSummary>;
-
 export type RecommendationSummariesOffsetPagination = OffsetPagination<RecommendationSummary>;
 
+export type AnalysisSummariesOffsetPagination = OffsetPagination<AnalysisSummary>;
+
 export interface Analysis {
   /**
    * Discovery run ID used to poll analysis status.
@@ -124,7 +96,7 @@ export interface Analysis {
   finished_at: string | null;
 
   /**
-   * Lifecycle status of the background analysis.
+   * Lifecycle status of a background analysis.
    */
   status: 'running' | 'completed' | 'failed' | 'canceled';
 }
@@ -162,6 +134,21 @@ export interface Browser {
   viewport: Shared.BrowserViewport;
 }
 
+export interface ConfigRegistryResponse {
+  /**
+   * Pollable analysis after workflow submission is acknowledged. Null when no
+   * refresh was submitted.
+   */
+  analysis: Analysis | null;
+
+  /**
+   * A recommendation or a structured no-recommendation result.
+   */
+  recommendation: RecommendationResult | null;
+
+  target: Target;
+}
+
 export interface Evidence {
   accessed: number;
 
@@ -216,8 +203,7 @@ export interface LookupResponse {
 
 export interface NoRecommendation {
   /**
-   * Machine-readable reason Kernel cannot currently provide a Site Config
-   * recommendation.
+   * Machine-readable reason Kernel cannot currently provide a config recommendation.
    */
   code: 'proxy_restricted' | 'no_working_configuration' | 'inconclusive';
 
@@ -232,13 +218,13 @@ export interface NoRecommendation {
 /**
  * Proxy recipe for the recommended browser.
  */
-export type Proxy = Proxy.SiteConfigDirectProxy | Proxy.SiteConfigManagedProxy;
+export type Proxy = Proxy.ConfigRegistryDirectProxy | Proxy.ConfigRegistryManagedProxy;
 
 export namespace Proxy {
   /**
    * Direct egress recipe. Pass `{ "mode": "direct" }` as the browser's `proxy`.
    */
-  export interface SiteConfigDirectProxy {
+  export interface ConfigRegistryDirectProxy {
     mode: 'direct';
   }
 
@@ -247,16 +233,16 @@ export namespace Proxy {
    * create the resource once, retain its ID, and reuse that ID as the browser's
    * `proxy.id`. Do not submit this recipe before every browser session.
    */
-  export interface SiteConfigManagedProxy {
+  export interface ConfigRegistryManagedProxy {
     /**
      * Configuration for routing traffic through a proxy.
      */
-    create: SiteConfigManagedProxy.Create;
+    create: ConfigRegistryManagedProxy.Create;
 
     mode: 'managed';
   }
 
-  export namespace SiteConfigManagedProxy {
+  export namespace ConfigRegistryManagedProxy {
     /**
      * Configuration for routing traffic through a proxy.
      */
@@ -444,6 +430,16 @@ export interface Recommendation {
 export type RecommendationResult = Recommendation | NoRecommendation;
 
 export interface RecommendationSummary {
+  /**
+   * ID of the most recently requested analysis for this domain.
+   */
+  analysis_id: string;
+
+  /**
+   * Lifecycle status of the most recently requested analysis for this domain.
+   */
+  analysis_status: 'running' | 'completed' | 'failed' | 'canceled';
+
   /**
    * Most recent time the selected project requested an analysis for this domain.
    */
@@ -485,21 +481,6 @@ export interface ResolveRequest {
   allowed_proxy_countries?: Array<string>;
 }
 
-export interface SiteConfigResponse {
-  /**
-   * Pollable analysis after workflow submission is acknowledged. Null when no
-   * refresh was submitted.
-   */
-  analysis: Analysis | null;
-
-  /**
-   * A recommendation or a structured no-recommendation result.
-   */
-  recommendation: RecommendationResult | null;
-
-  target: Target;
-}
-
 export interface Target {
   /**
    * Registrable domain.
@@ -517,15 +498,19 @@ export interface Target {
   normalized: string;
 }
 
-export interface SiteConfigListParams extends OffsetPaginationParams {}
+export interface ConfigRegistryListParams extends OffsetPaginationParams {
+  /**
+   * Case-insensitive domain search. Full URLs are reduced to their registrable
+   * domain.
+   */
+  search?: string;
 
-export interface SiteConfigListRecommendationsParams extends OffsetPaginationParams {
-  sort_by?: 'target' | 'recommended_config' | 'last_requested_at' | 'success_rate';
+  sort_by?: 'target' | 'analysis_status' | 'recommended_config' | 'last_requested_at' | 'success_rate';
 
   sort_order?: 'asc' | 'desc';
 }
 
-export interface SiteConfigLookupParams {
+export interface ConfigRegistryLookupParams {
   /**
    * Public HTTP(S) URL to look up.
    */
@@ -538,7 +523,7 @@ export interface SiteConfigLookupParams {
   allowed_proxy_countries?: Array<string>;
 }
 
-export interface SiteConfigResolveParams {
+export interface ConfigRegistryResolveParams {
   /**
    * Public HTTP(S) URL to refresh.
    */
@@ -552,11 +537,14 @@ export interface SiteConfigResolveParams {
   allowed_proxy_countries?: Array<string>;
 }
 
-export declare namespace SiteConfigs {
+ConfigRegistry.Analyses = Analyses;
+
+export declare namespace ConfigRegistry {
   export {
     type Analysis as Analysis,
     type AnalysisSummary as AnalysisSummary,
     type Browser as Browser,
+    type ConfigRegistryResponse as ConfigRegistryResponse,
     type Evidence as Evidence,
     type LookupRequest as LookupRequest,
     type LookupResponse as LookupResponse,
@@ -566,13 +554,12 @@ export declare namespace SiteConfigs {
     type RecommendationResult as RecommendationResult,
     type RecommendationSummary as RecommendationSummary,
     type ResolveRequest as ResolveRequest,
-    type SiteConfigResponse as SiteConfigResponse,
     type Target as Target,
-    type AnalysisSummariesOffsetPagination as AnalysisSummariesOffsetPagination,
     type RecommendationSummariesOffsetPagination as RecommendationSummariesOffsetPagination,
-    type SiteConfigListParams as SiteConfigListParams,
-    type SiteConfigListRecommendationsParams as SiteConfigListRecommendationsParams,
-    type SiteConfigLookupParams as SiteConfigLookupParams,
-    type SiteConfigResolveParams as SiteConfigResolveParams,
+    type ConfigRegistryListParams as ConfigRegistryListParams,
+    type ConfigRegistryLookupParams as ConfigRegistryLookupParams,
+    type ConfigRegistryResolveParams as ConfigRegistryResolveParams,
   };
+
+  export { Analyses as Analyses, type AnalysisListParams as AnalysisListParams };
 }

package/src/resources/config-registry/index.ts

@@ -0,0 +1,25 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export { Analyses, type AnalysisListParams } from './analyses';
+export {
+  ConfigRegistry,
+  type Analysis,
+  type AnalysisSummary,
+  type Browser,
+  type ConfigRegistryResponse,
+  type Evidence,
+  type LookupRequest,
+  type LookupResponse,
+  type NoRecommendation,
+  type Proxy,
+  type Recommendation,
+  type RecommendationResult,
+  type RecommendationSummary,
+  type ResolveRequest,
+  type Target,
+  type ConfigRegistryListParams,
+  type ConfigRegistryLookupParams,
+  type ConfigRegistryResolveParams,
+  type AnalysisSummariesOffsetPagination,
+  type RecommendationSummariesOffsetPagination,
+} from './config-registry';

package/src/resources/config-registry.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './config-registry/index';