@onkernel/sdk 0.106.0 → 0.108.0

package/src/lib/config-registry-wait.ts

@@ -0,0 +1,133 @@
+import { APIConnectionTimeoutError, APIUserAbortError, KernelError } from '../core/error';
+import { buildHeaders } from '../internal/headers';
+import type { RequestOptions } from '../internal/request-options';
+import type { ConfigRegistryResponse } from '../resources/config-registry/config-registry';
+
+const defaultPollIntervalMs = 5_000;
+const terminalStatuses = new Set(['completed', 'failed', 'canceled', 'expired']);
+
+export type ConfigRegistryAnalysisWaitOptions = Pick<
+  RequestOptions,
+  'headers' | 'maxRetries' | 'timeout' | 'fetchOptions' | 'signal' | 'defaultBaseURL'
+> & {
+  pollIntervalMs?: number;
+  maxWaitMs?: number | null;
+};
+
+type AnalysisRetriever = {
+  retrieve(id: string, options?: RequestOptions): Promise<ConfigRegistryResponse>;
+};
+
+const timeoutError = (id: string, polls: number, lastStatus: string | undefined, startedAt: number) =>
+  new APIConnectionTimeoutError({
+    message: `Timed out waiting for config registry analysis ${JSON.stringify(id)} after ${(
+      performance.now() - startedAt
+    ).toFixed(0)}ms and ${polls} polls; last status was ${JSON.stringify(lastStatus)}`,
+  });
+
+const wait = (ms: number, signal?: AbortSignal | null): Promise<void> => {
+  if (signal?.aborted) {
+    return Promise.reject(new APIUserAbortError());
+  }
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (error?: Error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+      if (error) reject(error);
+      else resolve();
+    };
+    const onAbort = () => finish(new APIUserAbortError());
+    const timer = setTimeout(() => finish(), ms);
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (signal?.aborted) onAbort();
+  });
+};
+
+const analysisFinished = (response: ConfigRegistryResponse, requestedID: string): [boolean, string] => {
+  const analysis = response.analysis;
+  if (!analysis || typeof analysis !== 'object') {
+    throw new KernelError(
+      `Config registry response for ${JSON.stringify(requestedID)} is missing an analysis`,
+    );
+  }
+  if (typeof analysis.id !== 'string' || !analysis.id) {
+    throw new KernelError(
+      `Config registry response for ${JSON.stringify(requestedID)} has no valid analysis ID`,
+    );
+  }
+  if (analysis.id !== requestedID) {
+    throw new KernelError(
+      `Config registry response for ${JSON.stringify(requestedID)} returned analysis ${JSON.stringify(
+        analysis.id,
+      )}`,
+    );
+  }
+  if (typeof analysis.status !== 'string' || !analysis.status) {
+    throw new KernelError(`Config registry analysis ${JSON.stringify(requestedID)} has no valid status`);
+  }
+  if (!Object.prototype.hasOwnProperty.call(analysis, 'finished_at')) {
+    throw new KernelError(`Config registry analysis ${JSON.stringify(requestedID)} is missing finished_at`);
+  }
+  if (
+    analysis.finished_at !== null &&
+    (typeof analysis.finished_at !== 'string' || Number.isNaN(Date.parse(analysis.finished_at)))
+  ) {
+    throw new KernelError(
+      `Config registry analysis ${JSON.stringify(requestedID)} has an invalid finished_at`,
+    );
+  }
+
+  return [analysis.finished_at !== null || terminalStatuses.has(analysis.status), analysis.status];
+};
+
+export async function waitForConfigRegistryAnalysis(
+  resource: AnalysisRetriever,
+  id: string,
+  options: ConfigRegistryAnalysisWaitOptions = {},
+): Promise<ConfigRegistryResponse> {
+  if (!id) {
+    throw new TypeError('id must be non-empty');
+  }
+  const { pollIntervalMs = defaultPollIntervalMs, maxWaitMs, ...requestOptions } = options;
+  if (!Number.isFinite(pollIntervalMs) || pollIntervalMs <= 0) {
+    throw new RangeError('pollIntervalMs must be finite and positive');
+  }
+  if (maxWaitMs != null && (!Number.isFinite(maxWaitMs) || maxWaitMs < 0)) {
+    throw new RangeError('maxWaitMs must be finite and non-negative');
+  }
+
+  const startedAt = performance.now();
+  const deadline = maxWaitMs == null ? undefined : startedAt + maxWaitMs;
+  const retrieveOptions: RequestOptions = {
+    ...requestOptions,
+    headers: buildHeaders([requestOptions.headers, { 'X-Stainless-Poll-Helper': 'true' }]),
+  };
+  let polls = 0;
+  let lastStatus: string | undefined;
+
+  while (true) {
+    if (polls > 0 && deadline !== undefined && performance.now() >= deadline) {
+      throw timeoutError(id, polls, lastStatus, startedAt);
+    }
+
+    // oxlint-disable-next-line no-await-in-loop -- each retrieval determines whether another poll is needed.
+    const response = await resource.retrieve(id, retrieveOptions);
+    polls += 1;
+    const [finished, status] = analysisFinished(response, id);
+    lastStatus = status;
+    if (finished) return response;
+
+    let delay = pollIntervalMs * (0.9 + Math.random() * 0.2);
+    if (deadline !== undefined) {
+      const remaining = deadline - performance.now();
+      if (remaining <= 0) throw timeoutError(id, polls, lastStatus, startedAt);
+      delay = Math.min(delay, remaining);
+    }
+    // oxlint-disable-next-line no-await-in-loop -- cancellation and the polling deadline must cover the delay.
+    await wait(delay, requestOptions.signal);
+  }
+}

package/src/resources/browsers/browsers.ts

@@ -149,9 +149,6 @@ import { multipartFormRequestOptions } from '../../internal/uploads';
 import { path } from '../../internal/utils/path';
 import { browserFetch, type BrowserFetchInit } from '../../lib/browser-fetch';
 
-/**
- * Create and manage browser sessions.
- */
 export class Browsers extends APIResource {
   telemetry: TelemetryAPI.Telemetry = new TelemetryAPI.Telemetry(this._client);
   replays: ReplaysAPI.Replays = new ReplaysAPI.Replays(this._client);
@@ -306,6 +303,33 @@ export class Browsers extends APIResource {
       ),
     );
   }
+
+  /**
+   * Execute JavaScript in a persistent Node.js runtime inside the browser VM.
+   * Top-level bindings, closures, mutations, and dynamically imported modules
+   * persist across calls until the REPL is reset or replaced. Start with
+   * `repl.help()` to list available methods, or call `repl.help("click")` for
+   * detailed help.
+   *
+   * Expression values are ignored. Emit ordered text or image output with
+   * `repl.write(...)`, console methods, or `repl.emitImage(...)`. The runtime also
+   * exposes browser-control helpers, WebMCP, Patchright, Playwright, and raw CDP.
+   *
+   * Executions are serialized. A timeout, crash, OOM, or protocol failure terminates
+   * the REPL and changes its `repl_id`. This is unrestricted code execution inside
+   * the browser VM and is not sandboxed.
+   *
+   * @example
+   * ```ts
+   * const browserReplResult = await client.browsers.repl(
+   *   'htzv5orfit78e1m2biiifpbv',
+   *   { code: 'code' },
+   * );
+   * ```
+   */
+  repl(idOrName: string, body: BrowserReplParams, options?: RequestOptions): APIPromise<BrowserReplResult> {
+    return this._client.post(path`/browsers/${idOrName}/repl`, { body, ...options });
+  }
 }
 
 export type BrowserListResponsesOffsetPagination = OffsetPagination<BrowserListResponse>;
@@ -434,6 +458,104 @@ export interface BrowserProxyConfig {
  */
 export type BrowserProxyMode = 'direct' | 'default';
 
+/**
+ * Ordered discriminated union of Browser REPL output items.
+ */
+export type BrowserReplContent = BrowserReplTextContent | BrowserReplImageContent;
+
+export interface BrowserReplImageContent {
+  data_b64: string;
+
+  mime_type: string;
+
+  type: 'image';
+}
+
+/**
+ * Request to execute code in the persistent Browser REPL.
+ */
+export interface BrowserReplRequest {
+  /**
+   * JavaScript evaluated in a persistent Node.js runtime. Top-level bindings persist
+   * until the browser VM's API process exits, the REPL is reset, or the REPL is
+   * terminated after a crash or timeout. Static top-level imports are unsupported;
+   * use dynamic `import()`. Expression values are ignored; emit output with
+   * `repl.write(...)`, console methods, or `repl.emitImage(...)`. May be empty only
+   * when `reset` is true.
+   */
+  code: string;
+
+  /**
+   * Terminate the current REPL, start a fresh one, and then evaluate code.
+   */
+  reset?: boolean;
+
+  /**
+   * Maximum execution time in seconds. Default is 60.
+   */
+  timeout_sec?: number;
+}
+
+/**
+ * Result of Browser REPL code execution.
+ */
+export interface BrowserReplResult {
+  /**
+   * CUID2 identifying the exact state-holding REPL process used for this execution.
+   * Stable across calls and Chromium reconnects; changes after an API restart,
+   * explicit reset, execution timeout, or REPL crash.
+   */
+  repl_id: string;
+
+  /**
+   * Whether the code executed successfully.
+   */
+  success: boolean;
+
+  /**
+   * Optional ordered text/image output produced by the execution.
+   */
+  content?: Array<BrowserReplContent>;
+
+  /**
+   * True if text or image output was dropped or truncated due to response limits.
+   */
+  content_truncated?: boolean;
+
+  /**
+   * Wall-clock execution time in milliseconds.
+   */
+  duration_ms?: number;
+
+  /**
+   * Error message if execution failed.
+   */
+  error?: string;
+
+  /**
+   * True if the REPL identified by `repl_id` was terminated by this request. The
+   * next request lazily starts a fresh REPL with a new `repl_id`.
+   */
+  repl_terminated?: boolean;
+
+  /**
+   * Stack trace if execution failed.
+   */
+  stack?: string;
+}
+
+export interface BrowserReplTextContent {
+  /**
+   * `write` is emitted by `repl.write`; `stdout` and `stderr` are emitted by console
+   * methods.
+   */
+  channel: 'write' | 'stdout' | 'stderr';
+
+  text: string;
+
+  type: 'text';
+}
+
 /**
  * Session usage metrics.
  */
@@ -1703,6 +1825,28 @@ export namespace BrowserLoadExtensionsParams {
   }
 }
 
+export interface BrowserReplParams {
+  /**
+   * JavaScript evaluated in a persistent Node.js runtime. Top-level bindings persist
+   * until the browser VM's API process exits, the REPL is reset, or the REPL is
+   * terminated after a crash or timeout. Static top-level imports are unsupported;
+   * use dynamic `import()`. Expression values are ignored; emit output with
+   * `repl.write(...)`, console methods, or `repl.emitImage(...)`. May be empty only
+   * when `reset` is true.
+   */
+  code: string;
+
+  /**
+   * Terminate the current REPL, start a fresh one, and then evaluate code.
+   */
+  reset?: boolean;
+
+  /**
+   * Maximum execution time in seconds. Default is 60.
+   */
+  timeout_sec?: number;
+}
+
 Browsers.Telemetry = TelemetryAPITelemetry;
 Browsers.Replays = Replays;
 Browsers.Fs = Fs;
@@ -1721,6 +1865,11 @@ export declare namespace Browsers {
     type BrowserProxy as BrowserProxy,
     type BrowserProxyConfig as BrowserProxyConfig,
     type BrowserProxyMode as BrowserProxyMode,
+    type BrowserReplContent as BrowserReplContent,
+    type BrowserReplImageContent as BrowserReplImageContent,
+    type BrowserReplRequest as BrowserReplRequest,
+    type BrowserReplResult as BrowserReplResult,
+    type BrowserReplTextContent as BrowserReplTextContent,
     type BrowserUsage as BrowserUsage,
     type Profile as Profile,
     type Tags as Tags,
@@ -1737,6 +1886,7 @@ export declare namespace Browsers {
     type BrowserListParams as BrowserListParams,
     type BrowserCurlParams as BrowserCurlParams,
     type BrowserLoadExtensionsParams as BrowserLoadExtensionsParams,
+    type BrowserReplParams as BrowserReplParams,
   };
 
   export {

package/src/resources/browsers/index.ts

@@ -9,6 +9,11 @@ export {
   type BrowserProxy,
   type BrowserProxyConfig,
   type BrowserProxyMode,
+  type BrowserReplContent,
+  type BrowserReplImageContent,
+  type BrowserReplRequest,
+  type BrowserReplResult,
+  type BrowserReplTextContent,
   type BrowserUsage,
   type Profile,
   type Tags,
@@ -24,6 +29,7 @@ export {
   type BrowserListParams,
   type BrowserCurlParams,
   type BrowserLoadExtensionsParams,
+  type BrowserReplParams,
   type ProfilesOffsetPagination,
   type BrowserListResponsesOffsetPagination,
 } from './browsers';

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

@@ -7,6 +7,10 @@ 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 {
+  waitForConfigRegistryAnalysis,
+  type ConfigRegistryAnalysisWaitOptions,
+} from '../../lib/config-registry-wait';
 
 /**
  * Resolve browser and proxy recommendations for bot-protected sites.
@@ -26,6 +30,20 @@ export class Analyses extends APIResource {
     return this._client.get(path`/config-registry/analyses/${id}`, options);
   }
 
+  /**
+   * Wait for an analysis to finish and return its complete result.
+   *
+   * The first retrieval happens immediately. `maxWaitMs` is a soft polling
+   * deadline: an in-flight request and its normal retries may finish after it.
+   * Timing out or aborting does not cancel the remote analysis.
+   */
+  async waitForResult(
+    id: string,
+    options?: ConfigRegistryAnalysisWaitOptions,
+  ): Promise<ConfigRegistryAPI.ConfigRegistryResponse> {
+    return await waitForConfigRegistryAnalysis(this, id, options);
+  }
+
   /**
    * Lists analyses for the selected project, newest first.
    *
@@ -73,7 +91,10 @@ export interface AnalysisListParams extends OffsetPaginationParams {
 }
 
 export declare namespace Analyses {
-  export { type AnalysisListParams as AnalysisListParams };
+  export {
+    type AnalysisListParams as AnalysisListParams,
+    type ConfigRegistryAnalysisWaitOptions as ConfigRegistryAnalysisWaitOptions,
+  };
 }
 
-export { type AnalysisSummariesOffsetPagination };
+export { type AnalysisSummariesOffsetPagination, type ConfigRegistryAnalysisWaitOptions };

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

@@ -261,7 +261,7 @@ export interface NoRecommendation {
   /**
    * Machine-readable reason Kernel cannot currently provide a config recommendation.
    */
-  code: 'proxy_restricted' | 'no_working_configuration' | 'inconclusive';
+  code: 'proxy_restricted' | 'target_not_evaluable' | 'no_working_configuration' | 'inconclusive';
 
   /**
    * Human-readable explanation suitable for display.

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

@@ -1,6 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-export { Analyses, type AnalysisListParams } from './analyses';
+export { Analyses, type AnalysisListParams, type ConfigRegistryAnalysisWaitOptions } from './analyses';
 export {
   ConfigRegistry,
   type Analysis,

package/src/resources/index.ts

@@ -47,6 +47,11 @@ export {
   type BrowserProxy,
   type BrowserProxyConfig,
   type BrowserProxyMode,
+  type BrowserReplContent,
+  type BrowserReplImageContent,
+  type BrowserReplRequest,
+  type BrowserReplResult,
+  type BrowserReplTextContent,
   type BrowserUsage,
   type Profile,
   type Tags,
@@ -62,6 +67,7 @@ export {
   type BrowserListParams,
   type BrowserCurlParams,
   type BrowserLoadExtensionsParams,
+  type BrowserReplParams,
   type ProfilesOffsetPagination,
   type BrowserListResponsesOffsetPagination,
 } from './browsers/browsers';

package/src/resources/vaults/items.ts

@@ -133,8 +133,10 @@ export class Items extends APIResource {
    * device approval before native Square Pay. Keep the returned approval page open,
    * poll until ready_to_submit, then submit before preparation.expires_at. Unused
    * preparations expire automatically and cannot be reused. If spend-request
-   * creation is rate limited, returns HTTP 429 with code
-   * `spend_request_rate_limited`; stop and back off before retrying.
+   * creation is rejected with a non-retryable provider error, the card item is
+   * deleted and the provider's error code and message are returned. Rate limits
+   * return HTTP 429 and retain the card item; stop, back off, and retry the same
+   * authorize operation.
    *
    * Fill returns a value-free execution result. Validation failures before writing
    * return 400 (invalid request or targets), 403 (access or destination denied), 404
@@ -316,7 +318,8 @@ export namespace CardVaultItemSpec {
    */
   export interface LinkCardVaultItemSpec {
     /**
-     * Integer amount in minor currency units.
+     * Integer amount in minor currency units. Link permits at most 50000 per spend
+     * request.
      */
     amount: number;
 

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.106.0'; // x-release-please-version
+export const VERSION = '0.108.0'; // x-release-please-version

package/version.d.mts

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

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.106.0";
+export declare const VERSION = "0.108.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.106.0'; // x-release-please-version
+exports.VERSION = '0.108.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

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