@onkernel/sdk 0.125.0 → 0.126.0

package/src/resources/vaults/items.ts

@@ -43,7 +43,9 @@ export class Items extends APIResource {
    * remain unchanged and explicit empty lists clear them. Wallet/provider binding
    * and unsupported fields cannot change after authorization starts. An uncertain
    * update enters recovery_required and must not be retried. Checkout cards may be
-   * edited between authorizations.
+   * edited between authorizations. A Link card authorized with browser_id and
+   * page_url cannot be changed; delete it and create a new card with the updated
+   * details.
    *
    * @example
    * ```ts
@@ -132,10 +134,11 @@ export class Items extends APIResource {
    * `available_operations`, following its natural-language description. Availability
    * is rechecked at execution time; unavailable operations return 409. Authorization
    * and preparation may call an external provider and return updated state. Link
-   * cards advertise authorize without checkout context. Eligible unused AgentCard
-   * cards advertise prepare_checkout, which requires checkout context and obtains
-   * device approval before native Square Pay. Keep the returned approval page open,
-   * poll until ready_to_submit, then submit before preparation.expires_at. Unused
+   * cards advertise authorize; pass browser_id and page_url from the final checkout
+   * page so Kernel can inspect the checkout. Eligible unused AgentCard cards
+   * advertise prepare_checkout, which requires checkout context and obtains 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 rejected with a non-retryable provider error, the card item is
    * deleted and the provider's error code and message are returned. Rate limits
@@ -155,6 +158,8 @@ export class Items extends APIResource {
    *   await client.vaults.items.performOperation('key', {
    *     id_or_name: 'id_or_name',
    *     type: 'authorize',
+   *     browser_id: 'browser-session-id',
+   *     page_url: 'https://store.example.com/checkout',
    *   });
    * ```
    */
@@ -309,16 +314,39 @@ export type AgentcardPreparedProcessor =
 
 /**
  * Authorize a Link or Kernel card using its existing purchase specification. Use
- * only after explicit user approval and when the item advertises authorize. Do not
- * automatically retry provider failures or indeterminate outcomes. Checkout
- * context is not accepted.
+ * only after explicit user approval and when the item advertises authorize; follow
+ * the advertised operation's description. For a Link card, pass browser_id and
+ * page_url together while the browser is on the final checkout page: Kernel
+ * inspects that checkout, chooses how the credential is delivered, and limits fill
+ * to that checkout's origin in any browser with this vault attached. Omitting both
+ * issues a virtual card that fills any page on the merchant origin. Once approval
+ * has been requested, browser_id and page_url are ignored and authorize only
+ * re-checks the request. Browser and checkout inspection errors occur before any
+ * provider request and can be retried once the browser is on the checkout page.
+ * Kernel cards do not accept browser_id or page_url.
  */
 export interface AuthorizeVaultItemOperationRequest {
   type: 'authorize';
+
+  /**
+   * Browser session ID, not a reusable browser name. The browser must have this
+   * vault attached.
+   */
+  browser_id?: string;
+
+  /**
+   * Exact current top-level URL of the final checkout page open in browser_id.
+   */
+  page_url?: string;
 }
 
 /**
- * Live payment card. Test-mode card creation is not supported.
+ * Live Link card request. Test-mode card creation is not supported. The spec can
+ * be changed with PATCH until the card is authorized at a checkout. Authorize it
+ * with the browser at final checkout: Kernel inspects the checkout through WebMCP
+ * and internally chooses a merchant-bound Link Pay Token when supported or a
+ * virtual card otherwise. Callers never receive or choose how the credential is
+ * delivered.
  */
 export type CardVaultItemSpec =
   | CardVaultItemSpec.LinkCardVaultItemSpec
@@ -327,12 +355,18 @@ export type CardVaultItemSpec =
 
 export namespace CardVaultItemSpec {
   /**
-   * Live payment card. Test-mode card creation is not supported.
+   * Live Link card request. Test-mode card creation is not supported. The spec can
+   * be changed with PATCH until the card is authorized at a checkout. Authorize it
+   * with the browser at final checkout: Kernel inspects the checkout through WebMCP
+   * and internally chooses a merchant-bound Link Pay Token when supported or a
+   * virtual card otherwise. Callers never receive or choose how the credential is
+   * delivered.
    */
   export interface LinkCardVaultItemSpec {
     /**
-     * Integer amount in minor currency units. Link permits at most 50000 per spend
-     * request.
+     * Integer amount in minor currency units. Link Pay Token execution permits at most
+     * 500000; virtual-card execution permits at most 50000. Authorization rejects a
+     * larger amount when the checkout requires a virtual card.
      */
     amount: number;
 
@@ -354,7 +388,7 @@ export namespace CardVaultItemSpec {
     provider: 'link';
 
     /**
-     * Wallet item key used to mint this card.
+     * Connected Link wallet item key.
      */
     wallet: string;
 
@@ -1127,32 +1161,18 @@ export interface CredentialVaultItemUpdateRequest {
 }
 
 /**
- * Fill selected fields from one ready credential or ready, unexpired Link or
- * Kernel card into a browser linked to its vault. Only invoke when the item
- * advertises `fill`. Browser and vault must belong to the same project. Kernel
- * checks access and allowed destinations before filling; providing a page URL does
- * not authorize a destination.
- *
- * Find exactly one open page matching `page_url`. Credential items may omit
- * `page_url` to require exactly one open page; cards require an HTTPS page URL.
- * Credentials have no destination allowlist. TOTP fields generate a current code
- * immediately before writing; their seeds never enter the browser. For each
- * selector, search the main frame and all descendant frames for editable inputs or
- * selects matched directly or contained within matching elements. Each selector
- * must resolve to one unique editable element across all frames; zero or multiple
- * candidates fail. Count each element once, even if multiple matching containers
- * contain it. Validate all bindings before filling. Select elements match an
- * option by its value, not its label. If the page navigates or a target disappears
- * during filling, stop rather than selecting a different page or element.
+ * Use a vault item in a browser session, for example to fill a login or payment
+ * form. Only invoke when the item advertises `fill`; the advertised operation
+ * describes the inputs that item needs. Requires `browser_id` and usually
+ * `page_url`; some items also require `fields`. Browser and vault must belong to
+ * the same project. Kernel checks access and allowed destinations before filling;
+ * providing a page URL does not authorize a destination.
  *
- * Fill in request order and stop on the first failure. This operation is not
- * atomic: previously filled fields are not rolled back. Never submit the form or
- * click buttons, though input/change events may trigger site behavior. Link and
- * Kernel cards use fill for browser checkout and do not expose aliases or support
- * egress substitution. Fill does not consume the item, so a failed or
- * indeterminate fill is safe to retry; a retry rewrites the same fields. A retry
- * right after an indeterminate fill may wait up to 15 seconds for the earlier
- * attempt's browser lock to expire.
+ * Fill never submits forms or clicks buttons, though input and change events may
+ * trigger site behavior. It is not atomic: completed steps are not rolled back.
+ * Fill does not consume the item, so a failed or indeterminate fill is safe to
+ * retry. A retry right after an indeterminate fill may wait up to 15 seconds for
+ * the earlier attempt's browser lock to expire.
  *
  * Secret values are never returned or included in operation logs, traces, audit
  * events, or error details. This does not prevent an agent with unrestricted
@@ -1165,19 +1185,25 @@ export interface FillVaultItemOperationRequest {
    */
   browser_id: string;
 
+  type: 'fill';
+
   /**
-   * Field bindings for this step. No two bindings may resolve to the same element.
+   * Field bindings, when the item's advertised fill operation requires them. Each
+   * selector is searched in the main frame and all descendant frames and must
+   * resolve to exactly one editable input or select, matched directly or through a
+   * containing element; zero or multiple candidates fail, and no two bindings may
+   * resolve to the same element. Select elements match an option by value, not
+   * label. All bindings are validated before any write, then filled in request
+   * order, stopping at the first failure. If the page navigates or a target
+   * disappears, fill stops rather than choosing another page or element.
    */
-  fields: Array<VaultFillField>;
-
-  type: 'fill';
+  fields?: Array<VaultFillField>;
 
   /**
    * Exact current top-level page URL, including path, query, and fragment. Must
    * match exactly one open page in the browser; zero or multiple matches fail. No
-   * prefix or glob matching. Required for cards, which must use HTTPS without
-   * embedded credentials. Optional for credentials, where omission requires exactly
-   * one open page.
+   * prefix or glob matching. When an item allows omitting it, the browser must have
+   * exactly one open page.
    */
   page_url?: string;
 
@@ -1189,15 +1215,16 @@ export interface FillVaultItemOperationRequest {
 
 export interface FillVaultItemOperationResult {
   /**
-   * Exactly one result per request binding, in request order. After the first failed
-   * or unknown field, all remaining fields are not_attempted.
+   * One result per request binding, in request order; empty when the fill used no
+   * bindings. After the first failed or unknown field, all remaining fields are
+   * not_attempted.
    */
   fields: Array<VaultFillFieldResult>;
 
   /**
-   * Completed only when all fields were filled. Failed when execution stopped with
-   * known outcomes. Unknown when any field's outcome cannot be determined. None of
-   * these statuses confirms payment or merchant acceptance.
+   * Completed when the fill finished. Failed when execution stopped with known
+   * outcomes. Unknown when an outcome cannot be determined. Completed means values
+   * were supplied to the page, not that the site accepted or submitted them.
    */
   status: 'completed' | 'failed' | 'unknown';
 
@@ -2103,6 +2130,11 @@ export namespace VaultItem {
 
     action?: ItemsAPI.VaultItemAction;
 
+    /**
+     * Server-generated provider and lifecycle guidance for agents.
+     */
+    description?: string;
+
     /**
      * Live, non-persisted data requested through the item GET expand parameter.
      */
@@ -2167,7 +2199,12 @@ export namespace VaultItem {
     key: string;
 
     /**
-     * Live payment card. Test-mode card creation is not supported.
+     * Live Link card request. Test-mode card creation is not supported. The spec can
+     * be changed with PATCH until the card is authorized at a checkout. Authorize it
+     * with the browser at final checkout: Kernel inspects the checkout through WebMCP
+     * and internally chooses a merchant-bound Link Pay Token when supported or a
+     * virtual card otherwise. Callers never receive or choose how the credential is
+     * delivered.
      */
     spec: ItemsAPI.CardVaultItemSpec;
 
@@ -2329,6 +2366,11 @@ export namespace VaultItemOperationResponse {
 
     action?: ItemsAPI.VaultItemAction;
 
+    /**
+     * Server-generated provider and lifecycle guidance for agents.
+     */
+    description?: string;
+
     /**
      * Live, non-persisted data requested through the item GET expand parameter.
      */
@@ -2393,7 +2435,12 @@ export namespace VaultItemOperationResponse {
     key: string;
 
     /**
-     * Live payment card. Test-mode card creation is not supported.
+     * Live Link card request. Test-mode card creation is not supported. The spec can
+     * be changed with PATCH until the card is authorized at a checkout. Authorize it
+     * with the browser at final checkout: Kernel inspects the checkout through WebMCP
+     * and internally chooses a merchant-bound Link Pay Token when supported or a
+     * virtual card otherwise. Callers never receive or choose how the credential is
+     * delivered.
      */
     spec: ItemsAPI.CardVaultItemSpec;
 
@@ -2755,7 +2802,12 @@ export declare namespace ItemUpdateParams {
     id_or_name: string;
 
     /**
-     * Body param: Live payment card. Test-mode card creation is not supported.
+     * Body param: Live Link card request. Test-mode card creation is not supported.
+     * The spec can be changed with PATCH until the card is authorized at a checkout.
+     * Authorize it with the browser at final checkout: Kernel inspects the checkout
+     * through WebMCP and internally chooses a merchant-bound Link Pay Token when
+     * supported or a virtual card otherwise. Callers never receive or choose how the
+     * credential is delivered.
      */
     spec: CardVaultItemSpec;
 
@@ -2842,6 +2894,18 @@ export declare namespace ItemPerformOperationParams {
      * Body param
      */
     type: 'authorize';
+
+    /**
+     * Body param: Browser session ID, not a reusable browser name. The browser must
+     * have this vault attached.
+     */
+    browser_id?: string;
+
+    /**
+     * Body param: Exact current top-level URL of the final checkout page open in
+     * browser_id.
+     */
+    page_url?: string;
   }
 
   export interface RestartVerificationVaultItemOperationRequest {
@@ -2948,22 +3012,27 @@ export declare namespace ItemPerformOperationParams {
     browser_id: string;
 
     /**
-     * Body param: Field bindings for this step. No two bindings may resolve to the
-     * same element.
+     * Body param
      */
-    fields: Array<VaultFillField>;
+    type: 'fill';
 
     /**
-     * Body param
+     * Body param: Field bindings, when the item's advertised fill operation requires
+     * them. Each selector is searched in the main frame and all descendant frames and
+     * must resolve to exactly one editable input or select, matched directly or
+     * through a containing element; zero or multiple candidates fail, and no two
+     * bindings may resolve to the same element. Select elements match an option by
+     * value, not label. All bindings are validated before any write, then filled in
+     * request order, stopping at the first failure. If the page navigates or a target
+     * disappears, fill stops rather than choosing another page or element.
      */
-    type: 'fill';
+    fields?: Array<VaultFillField>;
 
     /**
      * Body param: Exact current top-level page URL, including path, query, and
      * fragment. Must match exactly one open page in the browser; zero or multiple
-     * matches fail. No prefix or glob matching. Required for cards, which must use
-     * HTTPS without embedded credentials. Optional for credentials, where omission
-     * requires exactly one open page.
+     * matches fail. No prefix or glob matching. When an item allows omitting it, the
+     * browser must have exactly one open page.
      */
     page_url?: string;
 
@@ -3315,7 +3384,12 @@ export declare namespace ItemUpsertParams {
     id_or_name: string;
 
     /**
-     * Body param: Live payment card. Test-mode card creation is not supported.
+     * Body param: Live Link card request. Test-mode card creation is not supported.
+     * The spec can be changed with PATCH until the card is authorized at a checkout.
+     * Authorize it with the browser at final checkout: Kernel inspects the checkout
+     * through WebMCP and internally chooses a merchant-bound Link Pay Token when
+     * supported or a virtual card otherwise. Callers never receive or choose how the
+     * credential is delivered.
      */
     spec: CardVaultItemSpec;
 

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.125.0'; // x-release-please-version
+export const VERSION = '0.126.0'; // x-release-please-version

package/version.d.mts

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

package/version.d.ts

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

package/version.mjs

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