@onkernel/sdk 0.119.0 → 0.120.0

package/src/resources/browsers/playwright/executors.ts

@@ -0,0 +1,123 @@
+// 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 { buildHeaders } from '../../../internal/headers';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+/**
+ * Execute Playwright code against the browser instance and manage the executors it runs in.
+ */
+export class Executors extends APIResource {
+  /**
+   * Lists the default executor first, then the named executors created by POST
+   * /browsers/{id_or_name}/playwright/execute. Each entry reports whether a call is
+   * running on it and, for named executors, the target ID and URL of the tab it
+   * owns. Returns 404 for a browser whose image predates executors.
+   *
+   * @example
+   * ```ts
+   * const executorList =
+   *   await client.browsers.playwright.executors.list(
+   *     'htzv5orfit78e1m2biiifpbv',
+   *   );
+   * ```
+   */
+  list(idOrName: string, options?: RequestOptions): APIPromise<ExecutorList> {
+    return this._client.get(path`/browsers/${idOrName}/playwright/executors`, options);
+  }
+
+  /**
+   * Stops the executor's process. A call running on it fails with an error saying
+   * the executor was deleted. By default the executor's tab is closed too. The name
+   * can be reused; the next call with it creates a new executor and tab.
+   *
+   * The default executor is restarted instead of removed: its process is stopped, a
+   * call running on it fails with an error saying the executor was restarted, and
+   * queued and later calls run on a new process. It owns no tab, so 'close_tab' has
+   * no effect on it.
+   *
+   * @example
+   * ```ts
+   * await client.browsers.playwright.executors.delete(
+   *   'checkout',
+   *   { id_or_name: 'htzv5orfit78e1m2biiifpbv' },
+   * );
+   * ```
+   */
+  delete(name: string, params: ExecutorDeleteParams, options?: RequestOptions): APIPromise<void> {
+    const { id_or_name, close_tab } = params;
+    return this._client.delete(path`/browsers/${id_or_name}/playwright/executors/${name}`, {
+      query: { close_tab },
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+/**
+ * A Playwright executor on the browser
+ */
+export interface Executor {
+  /**
+   * Whether a call is running on the executor
+   */
+  busy: boolean;
+
+  /**
+   * When the executor was created
+   */
+  created_at: string;
+
+  /**
+   * When the most recent call on the executor started
+   */
+  last_used_at: string;
+
+  /**
+   * Name of a Playwright executor. Calls with the same name run in the same
+   * executor, one at a time; the first call with a new name creates it. Calls on
+   * different executors run concurrently. 'default' names the executor that runs
+   * calls without a name.
+   */
+  name: string;
+
+  /**
+   * CDP page target ID of the executor's tab, once it has one. The default executor
+   * owns no tab.
+   */
+  target_id?: string;
+
+  /**
+   * Current URL of the executor's tab, when it is open
+   */
+  url?: string;
+}
+
+/**
+ * The default executor followed by the named executors
+ */
+export interface ExecutorList {
+  executors: Array<Executor>;
+}
+
+export interface ExecutorDeleteParams {
+  /**
+   * Path param: Browser session ID or name
+   */
+  id_or_name: string;
+
+  /**
+   * Query param: Close the executor's tab. Defaults to true.
+   */
+  close_tab?: boolean;
+}
+
+export declare namespace Executors {
+  export {
+    type Executor as Executor,
+    type ExecutorList as ExecutorList,
+    type ExecutorDeleteParams as ExecutorDeleteParams,
+  };
+}

package/src/resources/browsers/playwright/index.ts

@@ -0,0 +1,10 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export { Executors, type Executor, type ExecutorList, type ExecutorDeleteParams } from './executors';
+export {
+  Playwright,
+  type ExecutorLimitError,
+  type Tab,
+  type PlaywrightExecuteResponse,
+  type PlaywrightExecuteParams,
+} from './playwright';

package/src/resources/browsers/playwright/playwright.ts

@@ -0,0 +1,186 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as ExecutorsAPI from './executors';
+import { Executor, ExecutorDeleteParams, ExecutorList, Executors } from './executors';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+/**
+ * Execute Playwright code against the browser instance and manage the executors it runs in.
+ */
+export class Playwright extends APIResource {
+  executors: ExecutorsAPI.Executors = new ExecutorsAPI.Executors(this._client);
+
+  /**
+   * Execute arbitrary Playwright code in a fresh execution context against the
+   * browser. The code runs in the same VM as the browser, minimizing latency and
+   * maximizing throughput. It has access to 'page', 'context', 'browser', and
+   * 'webmcp' variables. Use 'webmcp.listTools()' to discover browser-wide WebMCP
+   * tools and 'webmcp.invokeTool(toolRef, input?, { timeoutSec? })' to invoke an
+   * exact registration. It can `return` a value, and this value is returned in the
+   * response.
+   *
+   * Every call runs in an executor: a dedicated Node.js process with its own browser
+   * connection. Calls on different executors run concurrently; calls on the same
+   * executor run one at a time. A timeout, crash, or blocked event loop in one
+   * executor does not affect other executors. After a timeout the executor keeps its
+   * process and drops its browser connection, so code abandoned by the timeout
+   * cannot keep driving the browser. After a crash or a blocked event loop, the next
+   * call on that executor starts a fresh process.
+   *
+   * Calls without 'executor' run in the executor named 'default', which always
+   * exists and is the same as passing 'executor: "default"'. In the default
+   * executor, 'page' is bound to an active tab reported by Chrome. In single-window
+   * sessions, this is the foreground tab. When multiple browser windows are open,
+   * Chrome reports one active tab per window and the selected window is unspecified.
+   * 'context' is the BrowserContext that owns the selected page. Use
+   * 'browser.contexts()' to select a context or page explicitly.
+   *
+   * Pass any other name to run the call in a named executor. The first call with a
+   * new name creates it. Each named executor owns a tab: its first call opens a new
+   * background tab in the default browser context, and 'page' is bound to that tab
+   * on every later call while it stays open. Opening it does not change the active
+   * tab of an existing window. If the tab is closed, the next call opens a new one
+   * and reports 'tab.created: true'. Executor code can still reach other tabs
+   * through 'context' and 'browser'; ownership only decides what 'page' is bound to.
+   * Use named executors to drive several tabs of one browser in parallel.
+   *
+   * A browser can have at most 8 named executors; the default executor does not
+   * count. A call that would create another returns 409 with the current executors;
+   * delete one with DELETE /browsers/{id_or_name}/playwright/executors/{name}. Named
+   * executors are not removed automatically while the browser runs; when it shuts
+   * down, they are removed and their tabs closed.
+   *
+   * A named call to a browser whose image predates executors fails with 400 instead
+   * of running on the active tab; calls without 'executor' keep working on every
+   * image.
+   *
+   * @example
+   * ```ts
+   * const response = await client.browsers.playwright.execute(
+   *   'htzv5orfit78e1m2biiifpbv',
+   *   { code: 'code' },
+   * );
+   * ```
+   */
+  execute(
+    idOrName: string,
+    body: PlaywrightExecuteParams,
+    options?: RequestOptions,
+  ): APIPromise<PlaywrightExecuteResponse> {
+    return this._client.post(path`/browsers/${idOrName}/playwright/execute`, { body, ...options });
+  }
+}
+
+/**
+ * Returned when a call would create a named executor beyond the per-browser limit
+ */
+export interface ExecutorLimitError {
+  /**
+   * The default executor and the named executors that already exist
+   */
+  executors: Array<ExecutorsAPI.Executor>;
+
+  /**
+   * Human-readable error description
+   */
+  message: string;
+}
+
+/**
+ * The tab 'page' was bound to for this call. Absent if the call failed before
+ * binding a tab.
+ */
+export interface Tab {
+  /**
+   * Whether this call opened the tab. For a named executor this happens on its first
+   * call and after its previous tab was closed. For the default executor it happens
+   * only when the browser had no open page.
+   */
+  created: boolean;
+
+  /**
+   * CDP page target ID of the tab
+   */
+  target_id: string;
+}
+
+/**
+ * Result of Playwright code execution
+ */
+export interface PlaywrightExecuteResponse {
+  /**
+   * Whether the code executed successfully
+   */
+  success: boolean;
+
+  /**
+   * Error message if execution failed
+   */
+  error?: string;
+
+  /**
+   * The value returned by the code (if any)
+   */
+  result?: unknown;
+
+  /**
+   * Standard error from the execution
+   */
+  stderr?: string;
+
+  /**
+   * Standard output from the execution
+   */
+  stdout?: string;
+
+  /**
+   * The tab 'page' was bound to for this call. Absent if the call failed before
+   * binding a tab.
+   */
+  tab?: Tab;
+}
+
+export interface PlaywrightExecuteParams {
+  /**
+   * TypeScript/JavaScript code to execute. The code has access to 'page', 'context',
+   * and 'browser' variables. It runs within a function, so you can use a return
+   * statement at the end to return a value. This value is returned as the `result`
+   * property in the response. Example: "await page.goto('https://example.com');
+   * return await page.title();"
+   */
+  code: string;
+
+  /**
+   * Name of a Playwright executor. Calls with the same name run in the same
+   * executor, one at a time; the first call with a new name creates it. Calls on
+   * different executors run concurrently. 'default' names the executor that runs
+   * calls without a name.
+   */
+  executor?: string;
+
+  /**
+   * Maximum execution time in seconds. Default is 60.
+   */
+  timeout_sec?: number;
+}
+
+Playwright.Executors = Executors;
+
+export declare namespace Playwright {
+  export {
+    type ExecutorLimitError as ExecutorLimitError,
+    type Tab as Tab,
+    type PlaywrightExecuteResponse as PlaywrightExecuteResponse,
+    type PlaywrightExecuteParams as PlaywrightExecuteParams,
+  };
+
+  export {
+    Executors as Executors,
+    type Executor as Executor,
+    type ExecutorList as ExecutorList,
+    type ExecutorDeleteParams as ExecutorDeleteParams,
+  };
+}

package/src/resources/browsers/playwright.ts

@@ -1,89 +1,3 @@
 // 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 { RequestOptions } from '../../internal/request-options';
-import { path } from '../../internal/utils/path';
-
-/**
- * Execute Playwright code against the browser instance.
- */
-export class Playwright extends APIResource {
-  /**
-   * Execute arbitrary Playwright code in a fresh execution context against the
-   * browser. The code runs in the same VM as the browser, minimizing latency and
-   * maximizing throughput. It has access to 'page', 'context', 'browser', and
-   * 'webmcp' variables. Use 'webmcp.listTools()' to discover browser-wide WebMCP
-   * tools and 'webmcp.invokeTool(toolRef, input?, { timeoutSec? })' to invoke an
-   * exact registration. It can `return` a value, and this value is returned in the
-   * response.
-   *
-   * @example
-   * ```ts
-   * const response = await client.browsers.playwright.execute(
-   *   'htzv5orfit78e1m2biiifpbv',
-   *   { code: 'code' },
-   * );
-   * ```
-   */
-  execute(
-    idOrName: string,
-    body: PlaywrightExecuteParams,
-    options?: RequestOptions,
-  ): APIPromise<PlaywrightExecuteResponse> {
-    return this._client.post(path`/browsers/${idOrName}/playwright/execute`, { body, ...options });
-  }
-}
-
-/**
- * Result of Playwright code execution
- */
-export interface PlaywrightExecuteResponse {
-  /**
-   * Whether the code executed successfully
-   */
-  success: boolean;
-
-  /**
-   * Error message if execution failed
-   */
-  error?: string;
-
-  /**
-   * The value returned by the code (if any)
-   */
-  result?: unknown;
-
-  /**
-   * Standard error from the execution
-   */
-  stderr?: string;
-
-  /**
-   * Standard output from the execution
-   */
-  stdout?: string;
-}
-
-export interface PlaywrightExecuteParams {
-  /**
-   * TypeScript/JavaScript code to execute. The code has access to 'page', 'context',
-   * and 'browser' variables. It runs within a function, so you can use a return
-   * statement at the end to return a value. This value is returned as the `result`
-   * property in the response. Example: "await page.goto('https://example.com');
-   * return await page.title();"
-   */
-  code: string;
-
-  /**
-   * Maximum execution time in seconds. Default is 60.
-   */
-  timeout_sec?: number;
-}
-
-export declare namespace Playwright {
-  export {
-    type PlaywrightExecuteResponse as PlaywrightExecuteResponse,
-    type PlaywrightExecuteParams as PlaywrightExecuteParams,
-  };
-}
+export * from './playwright/index';

package/src/resources/browsers/telemetry.ts

@@ -4325,12 +4325,13 @@ export namespace BrowserPlatformAPICallEvent {
 
 /**
  * A branded proxy-layer failure observed by the browser. Emitted when the metro
- * egress host-proxy serves a branded 5xx error page whose response carries the
- * X-Kernel-Proxy-Error header. Low-volume and carries a typed code. Its value is
- * per-session and per-URL attribution for sessions that already capture the
- * network stream: proxy failures are only observable while the CDP network
- * collector is running, so this is an opt-in refinement of the raw network events
- * rather than a default-on alerting signal.
+ * egress host-proxy serves a branded error page whose response carries the
+ * X-Kernel-Proxy-Error header: a 502 for proxy-layer failures, or a 403 when the
+ * session's network policy blocks the destination. Low-volume and carries a typed
+ * code. Its value is per-session and per-URL attribution for sessions that already
+ * capture the network stream: proxy failures are only observable while the CDP
+ * network collector is running, so this is an opt-in refinement of the raw network
+ * events rather than a default-on alerting signal.
  */
 export interface BrowserProxyErrorEvent {
   category: 'network';
@@ -4369,17 +4370,18 @@ export namespace BrowserProxyErrorEvent {
   export interface Data extends TelemetryAPI.BrowserEventContext {
     /**
      * Proxy-layer error code: the X-Kernel-Proxy-Error response header value from a
-     * branded 5xx error page served by the metro egress host-proxy. Values mirror what
-     * the proxy emits: destination_blocked, destination_route_unavailable,
-     * provider_blacklisted, provider_unreachable, provider_rejected,
-     * origin_tls_timeout, origin_response_incomplete, proxy_unavailable,
-     * restricted_route_unavailable, upstream_timeout, upstream_dns_failure,
-     * upstream_connect_failed. A header value the browser image does not recognize is
-     * reported as unknown, with the header value in raw_code.
+     * branded error page served by the metro egress host-proxy. Values mirror what the
+     * proxy emits: destination_blocked, destination_route_unavailable,
+     * network_policy_denied, provider_blacklisted, provider_unreachable,
+     * provider_rejected, origin_tls_timeout, origin_response_incomplete,
+     * proxy_unavailable, restricted_route_unavailable, upstream_timeout,
+     * upstream_dns_failure, upstream_connect_failed. A header value the browser image
+     * does not recognize is reported as unknown, with the header value in raw_code.
      */
     code:
       | 'destination_blocked'
       | 'destination_route_unavailable'
+      | 'network_policy_denied'
       | 'provider_blacklisted'
       | 'provider_unreachable'
       | 'provider_rejected'
@@ -4398,7 +4400,8 @@ export namespace BrowserProxyErrorEvent {
     request_id: string;
 
     /**
-     * HTTP response status of the branded error page (502).
+     * HTTP response status of the branded error page (502, or 403 for
+     * network_policy_denied).
      */
     status: number;
 

package/src/resources/invocations.ts

@@ -471,7 +471,7 @@ export namespace InvocationListBrowsersResponse {
     /**
      * Geographic region of the browser session. Fixed once the session is created.
      */
-    region: 'us-east' | 'eu-west' | 'ap-southeast';
+    region: 'us-east' | 'us-west' | 'eu-west' | 'ap-southeast';
 
     /**
      * Unique identifier for the browser session

package/src/resources/search/search.ts

@@ -202,7 +202,8 @@ export namespace ProviderTarget {
        */
       export interface Contents {
         /**
-         * Return query-relevant provider excerpts.
+         * Return query-relevant provider excerpts. Defaults to true for Exa search
+         * requests; set false to disable.
          */
         highlights?: boolean;
 
@@ -255,7 +256,8 @@ export namespace ProviderTarget {
       query?: Array<string>;
 
       /**
-       * Provider context size supported by the selected model.
+       * Amount of page content Perplexity extracts per result. Defaults to medium unless
+       * max_tokens or max_tokens_per_page is set.
        */
       search_context_size?: 'low' | 'medium' | 'high';
 

package/src/resources/vaults/items.ts

@@ -1123,22 +1123,24 @@ export interface FillVaultItemOperationResult {
 /**
  * A ready Kernel card retains its encrypted network token and one-time code for
  * the fill operation until the item's expires_at. Fill and submit checkout before
- * then. Visa cards can be enrolled, but Visa purchases are not yet supported and
- * authorize returns 400; supported Mastercard purchases need no cardholder
- * approval. masks.last4 is the enrolled card's last four digits; masks.token_last4
- * is the network token's last four digits shown to the merchant. Kernel cards do
- * not expose aliases or support egress substitution. Kernel does not observe
- * whether the merchant charged the card.
+ * then. Visa purchases require a spend_approval action before the code is issued;
+ * Mastercard purchases need no hosted approval. masks.last4 is the enrolled card's
+ * last four digits; masks.token_last4 is the network token's last four digits
+ * shown to the merchant. Kernel cards do not expose aliases or support egress
+ * substitution. Kernel does not observe whether the merchant charged the card.
  */
 export interface KernelCardState {
   provider: 'kernel';
 
   /**
-   * recovery_required means issuing the one-time code has an unresolved outcome.
-   * Kernel never issues another code for the item automatically, and the item cannot
-   * be deleted or replaced until the original attempt is reconciled with support.
-   * When status_reason says the provider refused retrieval before acceptance, no
-   * code was issued and a later read retries.
+   * pending_authorization on a Visa purchase waits for the cardholder to approve it
+   * through the spend_approval action; an unused link expires after 30 minutes.
+   * recovery_required means approving the purchase or issuing the one-time code has
+   * an unresolved outcome. Kernel never approves again or issues another code for
+   * the item automatically, and the item cannot be deleted or replaced until the
+   * original attempt is reconciled with support. When status_reason says the
+   * provider refused retrieval before acceptance, no code was issued and a later
+   * read retries. declined means the card network refused to issue a code.
    */
   status:
     | 'requested'
@@ -1179,10 +1181,12 @@ export namespace KernelCardState {
  * network token number, expiry and one-time 3-digit code. They are stored
  * encrypted for the fill operation, which types them only on merchant_url's
  * origin; the merchant's own checkout submits the payment. The one-time code is
- * valid until the item's expires_at; fill and submit checkout before then. Visa
- * cards can be enrolled, but Visa purchases are not yet supported: authorize
- * returns 400. Supported Mastercard purchases need no cardholder approval. Card
- * updates are not supported; delete and create a new item instead.
+ * valid until the item's expires_at; fill and submit checkout before then.
+ * Mastercard purchases need no cardholder approval. A Visa purchase returns a
+ * spend_approval action: the cardholder approves it with a Visa passkey, and
+ * Kernel registers a Visa intent for one transaction up to the amount before
+ * issuing the code. Card updates are not supported; delete and create a new item
+ * instead.
  */
 export interface KernelCardVaultItemSpec {
   /**
@@ -1210,6 +1214,12 @@ export interface KernelCardVaultItemSpec {
    * Key of the Kernel wallet item whose enrolled card pays.
    */
   wallet: string;
+
+  /**
+   * The merchant's ISO 3166-1 alpha-2 country code. Required for Visa cards, whose
+   * one-time code is issued for the merchant's country.
+   */
+  merchant_country?: string;
 }
 
 export interface KernelCredentialVaultItemSpec {
@@ -1273,10 +1283,11 @@ export interface KernelWalletState {
 
   /**
    * pending_authorization asks the cardholder to use the card_enrollment action.
-   * connected is ready for supported purchases. reconnect_required asks the
-   * cardholder to use a new card_enrollment action after an uncertain enrollment was
-   * safely removed. degraded means the enrollment outcome is unknown and the wallet
-   * must be deleted before adding another card.
+   * connected means the card is stored; it can pay once payment_methods reports
+   * capabilities.single_use_card.eligible. reconnect_required asks the cardholder to
+   * use a new card_enrollment action after an uncertain enrollment was safely
+   * removed. degraded means the enrollment outcome is unknown and the wallet must be
+   * deleted before adding another card.
    */
   status: 'pending_authorization' | 'connected' | 'reconnect_required' | 'degraded';
 
@@ -1284,13 +1295,16 @@ export interface KernelWalletState {
 }
 
 /**
- * One card Kernel enrolls for Visa or Mastercard agentic network tokens using
- * Kernel-managed credentials. Creation returns a card_enrollment action: the
- * cardholder enters the card and their email on a Kernel-hosted page, then Kernel
- * enrolls the securely stored card. The card number never reaches Kernel. The
- * connected wallet's payment_methods expansion lists the enrolled card. Visa cards
- * can be enrolled, but Visa purchases are not yet supported: authorize
- * returns 400.
+ * One card stored with Kernel-managed credentials. Creation returns a
+ * card*enrollment action: the cardholder enters the card and their email on a
+ * Kernel-hosted page, and the wallet connects once the card is stored. Kernel then
+ * enrolls it for an agentic network token when the issuer supports it. The card
+ * number never reaches Kernel. The connected wallet's payment_methods expansion
+ * lists the card; capabilities.single_use_card.eligible is false, with a
+ * network_token*\* reason, until the card has a network token, and authorize
+ * returns 400 for such a card. Visa purchases require the cardholder to complete a
+ * spend_approval action before Kernel issues a one-time code; Mastercard purchases
+ * need no hosted approval.
  */
 export interface KernelWalletVaultItemSpec {
   provider: 'kernel';

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.119.0'; // x-release-please-version
+export const VERSION = '0.120.0'; // x-release-please-version

package/version.d.mts

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

package/version.d.ts

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

package/version.mjs

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