@onkernel/sdk 0.100.0 → 0.102.0

package/resources/vaults/items.d.mts

@@ -9,34 +9,127 @@ export declare class Items extends APIResource {
      * description before using it. Expanded data is fetched from the provider and is
      * not persisted in the vault item. Requesting an unavailable expansion returns 409
      * instead of a partial item.
+     *
+     * @example
+     * ```ts
+     * const vaultItem = await client.vaults.items.retrieve('x', {
+     *   id_or_name: 'id_or_name',
+     * });
+     * ```
      */
     retrieve(key: string, params: ItemRetrieveParams, options?: RequestOptions): APIPromise<VaultItem>;
     /**
-     * Update a card specification before or between authorizations
+     * Requested cards accept a replacement specification. Pending issuance requests
+     * may update provider-supported fields on their existing request, subject to
+     * atomic provider approval checks; omitted optional fields 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.
+     *
+     * @example
+     * ```ts
+     * const vaultItem = await client.vaults.items.update('x', {
+     *   id_or_name: 'id_or_name',
+     *   spec: {
+     *     provider: 'link',
+     *     wallet: 'link-wallet',
+     *     payment_method_id: 'pm_example',
+     *     amount: 3000,
+     *     currency: 'usd',
+     *     merchant_name: 'Example Store',
+     *     merchant_url: 'https://store.example.com',
+     *     context:
+     *       'The order total changed to USD 30.00 including shipping and taxes for one notebook. Update this unapproved request rather than creating a second payment.',
+     *   },
+     * });
+     * ```
      */
     update(key: string, params: ItemUpdateParams, options?: RequestOptions): APIPromise<VaultItem>;
     /**
      * List vault items without secret values
+     *
+     * @example
+     * ```ts
+     * const vaultItems = await client.vaults.items.list(
+     *   'id_or_name',
+     * );
+     * ```
      */
     list(idOrName: string, options?: RequestOptions): APIPromise<ItemListResponse>;
     /**
-     * Delete a vault item and invalidate its secret value
+     * Unresolved payment operations normally block deletion, including operations on
+     * child cards of a wallet. An AgentCard card in recovery_required whose checkout
+     * create response returned no authorization ID may be explicitly abandoned by
+     * deleting that card directly; deleting its wallet or vault remains blocked.
+     * Deleting or recreating an item is not proof that a payment did not occur.
+     *
+     * @example
+     * ```ts
+     * await client.vaults.items.delete('x', {
+     *   id_or_name: 'id_or_name',
+     * });
+     * ```
      */
     delete(key: string, params: ItemDeleteParams, options?: RequestOptions): APIPromise<void>;
     /**
      * List immutable audit events for a vault item
+     *
+     * @example
+     * ```ts
+     * const vaultItemEvents = await client.vaults.items.events(
+     *   'key',
+     *   { id_or_name: 'id_or_name' },
+     * );
+     * ```
      */
     events(key: string, params: ItemEventsParams, options?: RequestOptions): APIPromise<ItemEventsResponse>;
     /**
      * Retrieve the item first and invoke only an operation listed in
-     * `available_operations`, following its natural-language description. Operations
-     * may call an external provider and can return the item's updated state. If the
-     * provider rate limits spend-request creation, returns HTTP 429 with code
+     * `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
+     * 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.
+     *
+     * Fill returns a value-free execution result. Validation failures before writing
+     * return 400 (invalid request or targets), 403 (access or destination denied), 404
+     * (resource not found), or 409 (item or browser not ready). Once writing starts,
+     * known partial failures and indeterminate field outcomes return 200 with status
+     * `failed` or `unknown`, not an automatic-retry signal. A transport error may
+     * leave the outcome unknown; do not automatically retry.
+     *
+     * @example
+     * ```ts
+     * const vaultItemOperationResponse =
+     *   await client.vaults.items.performOperation('key', {
+     *     id_or_name: 'id_or_name',
+     *     type: 'authorize',
+     *   });
+     * ```
      */
-    performOperation(key: string, params: ItemPerformOperationParams, options?: RequestOptions): APIPromise<VaultItem>;
+    performOperation(key: string, params: ItemPerformOperationParams, options?: RequestOptions): APIPromise<VaultItemOperationResponse>;
     /**
-     * Create or retrieve an identical vault item by immutable key
+     * Create an item under a key unique within its vault, or retrieve the existing
+     * item when its specification matches. An identical card PUT returns the existing
+     * card in any lifecycle state without polling the provider, reauthorizing,
+     * replacing aliases, or resetting recovery. Conflicting specifications return 409.
+     * Provider-specific authorization requirements and retry behavior are described in
+     * the item's request schema.
+     *
+     * @example
+     * ```ts
+     * const vaultItem = await client.vaults.items.upsert('x', {
+     *   id_or_name: 'id_or_name',
+     *   spec: { provider: 'link' },
+     *   type: 'card',
+     * });
+     * ```
      */
     upsert(key: string, params: ItemUpsertParams, options?: RequestOptions): APIPromise<VaultItem>;
 }
@@ -81,6 +174,41 @@ export interface AgentcardCheckoutAuthorization {
      */
     replay_status?: number;
 }
+/**
+ * One-use Square checkout preparation. Keep the approval page open through token
+ * handoff. The amount is display-only and does not constrain the merchant's
+ * eventual charge.
+ */
+export interface AgentcardCheckoutPreparation {
+    browser_id: string;
+    created_at: string;
+    environment: 'production' | 'sandbox';
+    merchant_origin: string;
+    /**
+     * Preparation consumed means egress claimed the preparation and it cannot be
+     * reused. It does not mean the attempt settled. Use the enclosing item's status as
+     * the lifecycle indicator; item consumed means the attempt settled, not that an
+     * order or charge succeeded.
+     */
+    status: 'creating' | 'awaiting_approval' | 'ready' | 'consumed' | 'cancelled' | 'expired' | 'unknown';
+    id?: string;
+    approval_url?: string;
+    /**
+     * When ready, the absolute deadline to submit the first native request; no later
+     * than provider readiness expiry or 30 seconds after Kernel first observes
+     * readiness. Polling never extends this deadline.
+     */
+    expires_at?: string;
+}
+/**
+ * Authorize a Link 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.
+ */
+export interface AuthorizeVaultItemOperationRequest {
+    type: 'authorize';
+}
 /**
  * Live payment card. Test-mode card creation is not supported.
  */
@@ -181,7 +309,14 @@ export type CardVaultItemState = CardVaultItemState.LinkCardState | CardVaultIte
 export declare namespace CardVaultItemState {
     interface LinkCardState {
         provider: 'link';
-        status: 'requested' | 'pending_authorization' | 'ready' | 'consumed' | 'expired' | 'declined';
+        /**
+         * recovery_required means an original provider operation has an unresolved
+         * outcome. Do not retry, delete, or replace it. Known references may be observed
+         * safely, but unknown creation without an ID and uncertain card-material retrieval
+         * require manual reconciliation with the provider or support. There is no reset or
+         * caller-asserted reconciliation operation.
+         */
+        status: 'requested' | 'pending_authorization' | 'ready' | 'consumed' | 'expired' | 'declined' | 'recovery_required';
         aliases?: ItemsAPI.VaultCardAliases;
         domains?: Array<string>;
         masks?: LinkCardState.Masks;
@@ -196,7 +331,18 @@ export declare namespace CardVaultItemState {
     }
     interface AgentCardCardState {
         provider: 'agentcard';
-        status: 'requested' | 'ready' | 'pending_approval' | 'degraded';
+        /**
+         * ready_to_submit is device readiness for at most 30 seconds. consumed means the
+         * prepared attempt has settled, not that an order succeeded. stopped cannot be
+         * reused. outcome_unknown requires merchant reconciliation and blocks new
+         * requests. recovery_required means the original checkout outcome is unresolved.
+         * Automatic reuse is blocked. Known authorization IDs must be reconciled through
+         * provider observations or support. When no authorization ID was returned, an
+         * explicitly confirmed item deletion may abandon the unresolved attempt so the
+         * caller can create a replacement; deletion does not prove that the original
+         * attempt failed. It does not mean declined or expired.
+         */
+        status: 'requested' | 'ready' | 'preparing' | 'ready_to_submit' | 'pending_approval' | 'consumed' | 'stopped' | 'outcome_unknown' | 'degraded' | 'recovery_required';
         aliases?: ItemsAPI.VaultCardAliases;
         /**
          * The in-flight or most recent checkout authorization. Present while a checkout is
@@ -204,6 +350,12 @@ export declare namespace CardVaultItemState {
          */
         authorization?: ItemsAPI.AgentcardCheckoutAuthorization;
         masks?: AgentCardCardState.Masks;
+        /**
+         * One-use Square checkout preparation. Keep the approval page open through token
+         * handoff. The amount is display-only and does not constrain the merchant's
+         * eventual charge.
+         */
+        preparation?: ItemsAPI.AgentcardCheckoutPreparation;
         status_reason?: string;
     }
     namespace AgentCardCardState {
@@ -214,12 +366,168 @@ export declare namespace CardVaultItemState {
         }
     }
 }
+/**
+ * Fill selected fields from one ready, unexpired card into a browser linked to its
+ * vault. Only supported for card items created from Link wallets. 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`. 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.
+ *
+ * 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. Fill is the
+ * preferred browser-checkout path. Aliases remain an alternative for explicitly
+ * chosen egress-substitution integrations. Do not automatically retry or fall back
+ * to aliases after a failed or indeterminate operation.
+ *
+ * Secret values are never returned or included in operation logs, traces, audit
+ * events, or error details. This does not prevent an agent with unrestricted
+ * browser access from reading values from the page or other browser observation
+ * surfaces.
+ */
+export interface FillVaultItemOperationRequest {
+    /**
+     * Browser session ID, not a reusable browser name.
+     */
+    browser_id: string;
+    /**
+     * Field bindings for this step. No two bindings may resolve to the same element.
+     */
+    fields: Array<VaultCardFillField>;
+    /**
+     * 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. Must use HTTPS without embedded credentials.
+     */
+    page_url: string;
+    type: 'fill';
+    /**
+     * Total operation deadline in milliseconds, not a per-field timeout.
+     */
+    timeout_ms?: number;
+}
+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.
+     */
+    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.
+     */
+    status: 'completed' | 'failed' | 'unknown';
+    type: 'fill';
+}
+/**
+ * Prepare an unused AgentCard card for Square checkout. Deliver the returned
+ * approval URL and keep the approval page open. Poll the item until
+ * ready_to_submit, then submit native Pay before preparation.expires_at. Readiness
+ * lasts at most 30 seconds. Unused preparations expire automatically. Preparations
+ * are single-use even after failure or expiry; do not automatically retry and
+ * reconcile uncertain outcomes with the merchant.
+ */
+export interface PrepareCheckoutVaultItemOperationRequest {
+    /**
+     * Required when preparing an unused AgentCard card for Square. Consent is bound to
+     * this browser and declared merchant origin, not a tab. Wait for the item's
+     * ready_to_submit status before native Pay and submit within its readiness
+     * deadline. Unused preparations expire automatically; every preparation is
+     * single-use, including after failure or expiry.
+     */
+    checkout: VaultCheckoutContext;
+    type: 'prepare_checkout';
+}
 export interface VaultCardAliases {
     cvc: string;
     exp_month: string;
     exp_year: string;
     number: string;
 }
+/**
+ * Combined expiration derived from the stored month and year; not a separate
+ * stored secret.
+ */
+export type VaultCardFillField = VaultCardFillField.VaultCardStoredFillField | VaultCardFillField.VaultCardExpirationFillField;
+export declare namespace VaultCardFillField {
+    interface VaultCardStoredFillField {
+        /**
+         * Field in the decrypted card, not an alias. Number and CVC preserve leading
+         * zeros; month uses two digits and year uses four digits. Billing fields use the
+         * provider's stored billing address (name, line1, line2, city, state, postal_code,
+         * country) without reformatting. Request only needed billing fields. An absent or
+         * empty requested billing field returns 400 field_unavailable before any browser
+         * writes; it does not make other card fields unavailable.
+         */
+        field: 'number' | 'exp_month' | 'exp_year' | 'cvc' | 'billing_name' | 'billing_line1' | 'billing_line2' | 'billing_city' | 'billing_state' | 'billing_postal_code' | 'billing_country';
+        /**
+         * CSS selector for an editable input or select, or a containing element. Must
+         * resolve to one unique editable element across all page frames.
+         */
+        selector: string;
+    }
+    /**
+     * Combined expiration derived from the stored month and year; not a separate
+     * stored secret.
+     */
+    interface VaultCardExpirationFillField {
+        field: 'expiration';
+        format: 'MM/YY' | 'MM/YYYY';
+        /**
+         * CSS selector for an editable input or select, or a containing element. Must
+         * resolve to one unique editable element across all page frames.
+         */
+        selector: string;
+    }
+}
+/**
+ * Required when preparing an unused AgentCard card for Square. Consent is bound to
+ * this browser and declared merchant origin, not a tab. Wait for the item's
+ * ready_to_submit status before native Pay and submit within its readiness
+ * deadline. Unused preparations expire automatically; every preparation is
+ * single-use, including after failure or expiry.
+ */
+export interface VaultCheckoutContext {
+    /**
+     * Active browser session with this vault bound to it.
+     */
+    browser_id: string;
+    /**
+     * Square environment, independent of the AgentCard credential mode.
+     */
+    environment: 'production' | 'sandbox';
+    /**
+     * Canonical HTTPS origin of the top-level merchant document, not the Square
+     * iframe. HTTP localhost is accepted for tests.
+     */
+    merchant_origin: string;
+}
+export interface VaultFillFieldResult {
+    /**
+     * Zero-based index into the request fields array.
+     */
+    index: number;
+    /**
+     * Filled means the fill action completed, not that the website retained or
+     * accepted the value.
+     */
+    status: 'filled' | 'failed' | 'not_attempted' | 'unknown';
+    /**
+     * Present only for failed or unknown fields. Never includes secret values, DOM
+     * content, or raw browser errors.
+     */
+    error_code?: 'target_changed' | 'element_not_found' | 'ambiguous_selector' | 'element_not_editable' | 'option_not_found' | 'timeout' | 'execution_failed';
+}
 export type VaultItem = VaultItem.WalletVaultItem | VaultItem.CardVaultItem;
 export declare namespace VaultItem {
     interface WalletVaultItem {
@@ -232,9 +540,12 @@ export declare namespace VaultItem {
          */
         key: string;
         /**
-         * AgentCard wallet. Mode (sandbox vs live) is fixed by the deployment's AgentCard
-         * credential; there is no per-item test flag. user_id may only reference a user
-         * already enrolled by a wallet in this organization.
+         * AgentCard wallet. Omit provider_config to use Kernel-managed credentials, or
+         * select a customer-owned configuration. Mode (sandbox vs live) is determined by
+         * the selected credential; there is no per-item test flag. Without user_id,
+         * creation returns a hosted enrollment action and Kernel polls until the user
+         * connects. user_id may only reference a user already enrolled by a wallet in this
+         * organization under the same configuration.
          */
         spec: ItemsAPI.WalletVaultItemSpec;
         state: ItemsAPI.WalletVaultItemState;
@@ -262,7 +573,7 @@ export declare namespace VaultItem {
          */
         interface AvailableOperation {
             description: string;
-            type: 'authorize';
+            type: 'authorize' | 'prepare_checkout' | 'fill';
         }
         /**
          * Live, non-persisted data requested through the item GET expand parameter.
@@ -305,7 +616,7 @@ export declare namespace VaultItem {
          */
         interface AvailableOperation {
             description: string;
-            type: 'authorize';
+            type: 'authorize' | 'prepare_checkout' | 'fill';
         }
     }
 }
@@ -348,6 +659,103 @@ export interface VaultItemEvent {
         [key: string]: unknown;
     };
 }
+/**
+ * Authorization and preparation return the existing item shape. Fill returns a
+ * value-free execution result; it does not persist transient field outcomes on the
+ * item.
+ */
+export type VaultItemOperationResponse = VaultItemOperationResponse.WalletVaultItem | VaultItemOperationResponse.CardVaultItem | FillVaultItemOperationResult;
+export declare namespace VaultItemOperationResponse {
+    interface WalletVaultItem {
+        id: string;
+        available_expansions: Array<WalletVaultItem.AvailableExpansion>;
+        available_operations: Array<WalletVaultItem.AvailableOperation>;
+        created_at: string;
+        /**
+         * Immutable item key assigned when the item is created.
+         */
+        key: string;
+        /**
+         * AgentCard wallet. Omit provider_config to use Kernel-managed credentials, or
+         * select a customer-owned configuration. Mode (sandbox vs live) is determined by
+         * the selected credential; there is no per-item test flag. Without user_id,
+         * creation returns a hosted enrollment action and Kernel polls until the user
+         * connects. user_id may only reference a user already enrolled by a wallet in this
+         * organization under the same configuration.
+         */
+        spec: ItemsAPI.WalletVaultItemSpec;
+        state: ItemsAPI.WalletVaultItemState;
+        type: 'wallet';
+        updated_at: string;
+        action?: ItemsAPI.VaultItemAction;
+        /**
+         * Live, non-persisted data requested through the item GET expand parameter.
+         */
+        expanded?: WalletVaultItem.Expanded;
+        expires_at?: string;
+    }
+    namespace WalletVaultItem {
+        /**
+         * Live data that can currently be requested by passing its type to the item GET
+         * expand parameter.
+         */
+        interface AvailableExpansion {
+            description: string;
+            type: 'payment_methods';
+        }
+        /**
+         * An operation that is currently valid for this item. Read the description before
+         * invoking it through the item operations endpoint.
+         */
+        interface AvailableOperation {
+            description: string;
+            type: 'authorize' | 'prepare_checkout' | 'fill';
+        }
+        /**
+         * Live, non-persisted data requested through the item GET expand parameter.
+         */
+        interface Expanded {
+            payment_methods?: Array<ItemsAPI.VaultPaymentMethod>;
+        }
+    }
+    interface CardVaultItem {
+        id: string;
+        available_expansions: Array<CardVaultItem.AvailableExpansion>;
+        available_operations: Array<CardVaultItem.AvailableOperation>;
+        created_at: string;
+        /**
+         * Immutable item key assigned when the item is created.
+         */
+        key: string;
+        /**
+         * Live payment card. Test-mode card creation is not supported.
+         */
+        spec: ItemsAPI.CardVaultItemSpec;
+        state: ItemsAPI.CardVaultItemState;
+        type: 'card';
+        updated_at: string;
+        action?: ItemsAPI.VaultItemAction;
+        expires_at?: string;
+    }
+    namespace CardVaultItem {
+        /**
+         * Live data that can currently be requested by passing its type to the item GET
+         * expand parameter.
+         */
+        interface AvailableExpansion {
+            description: string;
+            type: 'payment_methods';
+        }
+        /**
+         * An operation that is currently valid for this item. Read the description before
+         * invoking it through the item operations endpoint.
+         */
+        interface AvailableOperation {
+            description: string;
+            type: 'authorize' | 'prepare_checkout' | 'fill';
+        }
+    }
+}
 export interface VaultPaymentMethod {
     id: string;
     /**
@@ -387,9 +795,12 @@ export declare namespace VaultPaymentMethod {
     }
 }
 /**
- * AgentCard wallet. Mode (sandbox vs live) is fixed by the deployment's AgentCard
- * credential; there is no per-item test flag. user_id may only reference a user
- * already enrolled by a wallet in this organization.
+ * AgentCard wallet. Omit provider_config to use Kernel-managed credentials, or
+ * select a customer-owned configuration. Mode (sandbox vs live) is determined by
+ * the selected credential; there is no per-item test flag. Without user_id,
+ * creation returns a hosted enrollment action and Kernel polls until the user
+ * connects. user_id may only reference a user already enrolled by a wallet in this
+ * organization under the same configuration.
  */
 export type WalletVaultItemSpec = WalletVaultItemSpec.LinkWalletVaultItemSpec | WalletVaultItemSpec.AgentCardWalletVaultItemSpec;
 export declare namespace WalletVaultItemSpec {
@@ -399,24 +810,62 @@ export declare namespace WalletVaultItemSpec {
     }
     namespace LinkWalletVaultItemSpec {
         interface Authorization {
-            client: Authorization.Client;
+            client: Authorization.KernelManagedOAuthClient | Authorization.CustomerManagedOAuthClient;
             method: 'oauth';
         }
         namespace Authorization {
-            interface Client {
+            interface KernelManagedOAuthClient {
                 type: 'kernel_managed';
             }
+            interface CustomerManagedOAuthClient {
+                /**
+                 * Select a provider config by ID or name. Responses return the ID. Renaming a
+                 * config does not change existing wallet bindings; a wallet cannot switch to a
+                 * different config after creation.
+                 */
+                provider_config: CustomerManagedOAuthClient.ProviderConfig;
+                type: 'customer_managed';
+            }
+            namespace CustomerManagedOAuthClient {
+                /**
+                 * Select a provider config by ID or name. Responses return the ID. Renaming a
+                 * config does not change existing wallet bindings; a wallet cannot switch to a
+                 * different config after creation.
+                 */
+                interface ProviderConfig {
+                    id?: string;
+                    name?: string;
+                }
+            }
         }
     }
     /**
-     * AgentCard wallet. Mode (sandbox vs live) is fixed by the deployment's AgentCard
-     * credential; there is no per-item test flag. user_id may only reference a user
-     * already enrolled by a wallet in this organization.
+     * AgentCard wallet. Omit provider_config to use Kernel-managed credentials, or
+     * select a customer-owned configuration. Mode (sandbox vs live) is determined by
+     * the selected credential; there is no per-item test flag. Without user_id,
+     * creation returns a hosted enrollment action and Kernel polls until the user
+     * connects. user_id may only reference a user already enrolled by a wallet in this
+     * organization under the same configuration.
      */
     interface AgentCardWalletVaultItemSpec {
         provider: 'agentcard';
+        /**
+         * Select an AgentCard configuration. The wallet's configuration cannot be changed
+         * after creation.
+         */
+        provider_config?: AgentCardWalletVaultItemSpec.ProviderConfig;
         user_id?: string;
     }
+    namespace AgentCardWalletVaultItemSpec {
+        /**
+         * Select an AgentCard configuration. The wallet's configuration cannot be changed
+         * after creation.
+         */
+        interface ProviderConfig {
+            id?: string;
+            name?: string;
+        }
+    }
 }
 export type WalletVaultItemState = WalletVaultItemState.LinkWalletState | WalletVaultItemState.AgentCardWalletState;
 export declare namespace WalletVaultItemState {
@@ -480,15 +929,66 @@ export interface ItemEventsParams {
      */
     wait?: number;
 }
-export interface ItemPerformOperationParams {
-    /**
-     * Path param
-     */
-    id_or_name: string;
-    /**
-     * Body param
-     */
-    type: 'authorize';
+export type ItemPerformOperationParams = ItemPerformOperationParams.AuthorizeVaultItemOperationRequest | ItemPerformOperationParams.PrepareCheckoutVaultItemOperationRequest | ItemPerformOperationParams.FillVaultItemOperationRequest;
+export declare namespace ItemPerformOperationParams {
+    interface AuthorizeVaultItemOperationRequest {
+        /**
+         * Path param
+         */
+        id_or_name: string;
+        /**
+         * Body param
+         */
+        type: 'authorize';
+    }
+    interface PrepareCheckoutVaultItemOperationRequest {
+        /**
+         * Path param
+         */
+        id_or_name: string;
+        /**
+         * Body param: Required when preparing an unused AgentCard card for Square. Consent
+         * is bound to this browser and declared merchant origin, not a tab. Wait for the
+         * item's ready_to_submit status before native Pay and submit within its readiness
+         * deadline. Unused preparations expire automatically; every preparation is
+         * single-use, including after failure or expiry.
+         */
+        checkout: VaultCheckoutContext;
+        /**
+         * Body param
+         */
+        type: 'prepare_checkout';
+    }
+    interface FillVaultItemOperationRequest {
+        /**
+         * Path param
+         */
+        id_or_name: string;
+        /**
+         * Body param: Browser session ID, not a reusable browser name.
+         */
+        browser_id: string;
+        /**
+         * Body param: Field bindings for this step. No two bindings may resolve to the
+         * same element.
+         */
+        fields: Array<VaultCardFillField>;
+        /**
+         * 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. Must use HTTPS without embedded
+         * credentials.
+         */
+        page_url: string;
+        /**
+         * Body param
+         */
+        type: 'fill';
+        /**
+         * Body param: Total operation deadline in milliseconds, not a per-field timeout.
+         */
+        timeout_ms?: number;
+    }
 }
 export type ItemUpsertParams = ItemUpsertParams.WalletVaultItemRequest | ItemUpsertParams.CardVaultItemRequest;
 export declare namespace ItemUpsertParams {
@@ -498,16 +998,142 @@ export declare namespace ItemUpsertParams {
          */
         id_or_name: string;
         /**
-         * Body param: AgentCard wallet. Mode (sandbox vs live) is fixed by the
-         * deployment's AgentCard credential; there is no per-item test flag. user_id may
-         * only reference a user already enrolled by a wallet in this organization.
+         * Body param: AgentCard wallet. Omit provider_config to use Kernel-managed
+         * credentials, or select a customer-owned configuration. Mode (sandbox vs live) is
+         * determined by the selected credential; there is no per-item test flag. Without
+         * user_id, creation returns a hosted enrollment action and Kernel polls until the
+         * user connects. user_id may only reference a user already enrolled by a wallet in
+         * this organization under the same configuration.
          */
-        spec: WalletVaultItemSpec;
+        spec: WalletVaultItemRequest.LinkWalletVaultItemRequestSpec | WalletVaultItemRequest.AgentCardWalletVaultItemSpec;
         /**
          * Body param
          */
         type: 'wallet';
     }
+    namespace WalletVaultItemRequest {
+        interface LinkWalletVaultItemRequestSpec {
+            /**
+             * Kernel starts and completes the user's Link authorization flow.
+             */
+            authorization: LinkWalletVaultItemRequestSpec.KernelManagedLinkAuthorizationInput | LinkWalletVaultItemRequestSpec.ImportedLinkAuthorizationInput;
+            provider: 'link';
+        }
+        namespace LinkWalletVaultItemRequestSpec {
+            /**
+             * Kernel starts and completes the user's Link authorization flow.
+             */
+            interface KernelManagedLinkAuthorizationInput {
+                client: KernelManagedLinkAuthorizationInput.Client;
+                method: 'oauth';
+            }
+            namespace KernelManagedLinkAuthorizationInput {
+                interface Client {
+                    type: 'kernel_managed';
+                }
+            }
+            /**
+             * The customer's backend completes Link OAuth and supplies the resulting tokens.
+             * For a new wallet, Kernel verifies the access token can access Link payment
+             * methods without consuming or rotating the refresh token. Valid access creates a
+             * wallet with state.status=connected. An expired, invalid, revoked, or
+             * insufficiently scoped access token returns 400 and no wallet is created. Refresh
+             * expired tokens in your backend before importing them. A failed import does not
+             * modify existing wallets. After successful import, Kernel owns subsequent
+             * refresh-token rotation; the customer must stop refreshing this grant. Import
+             * does not verify the refresh token: if it or the configured client credentials
+             * are rejected during a later refresh, the imported wallet becomes degraded. An
+             * unknown refresh outcome also leaves it degraded; Kernel does not retry a refresh
+             * token that may already have been consumed. There is no in-place reauthorization
+             * operation for an imported wallet. If this imported wallet's credentials become
+             * unusable, obtain a fresh Link OAuth grant in your backend and create a wallet
+             * under a NEW wallet key. Use the new wallet for NEW cards and payments, not to
+             * retry an old payment whose outcome is uncertain. This does not replace the old
+             * grant, rebind existing cards, or resolve their payment outcomes. Retain the old
+             * wallet and its cards while reconciling any uncertain payments with the provider
+             * or support. Do not repeat an uncertain payment on the new wallet, and do not
+             * treat deletion as evidence that it did not execute. Deletion of the old wallet
+             * can remain blocked by unresolved child cards. Repeating a create for the same
+             * item key and non-secret spec returns the existing wallet without replacing
+             * tokens, even if they have rotated or the wallet needs reconnection. ID and name
+             * references resolving to the same config are equivalent. A different config or
+             * non-secret spec returns 409. This create operation does not replace an existing
+             * grant.
+             */
+            interface ImportedLinkAuthorizationInput {
+                client: ImportedLinkAuthorizationInput.Client;
+                method: 'oauth';
+                /**
+                 * Send the token pair from your backend. Both tokens must be from the same Link
+                 * grant under the referenced client. Supply a currently valid access token. Kernel
+                 * refreshes when needed after import and uses the expiry returned by Link for
+                 * subsequent tokens. Tokens are never returned in wallet responses, events, or
+                 * logs.
+                 */
+                tokens: ImportedLinkAuthorizationInput.Tokens;
+            }
+            namespace ImportedLinkAuthorizationInput {
+                interface Client {
+                    /**
+                     * Select a provider config by ID or name. Responses return the ID. Renaming a
+                     * config does not change existing wallet bindings; a wallet cannot switch to a
+                     * different config after creation.
+                     */
+                    provider_config: Client.ProviderConfig;
+                    type: 'customer_managed';
+                }
+                namespace Client {
+                    /**
+                     * Select a provider config by ID or name. Responses return the ID. Renaming a
+                     * config does not change existing wallet bindings; a wallet cannot switch to a
+                     * different config after creation.
+                     */
+                    interface ProviderConfig {
+                        id?: string;
+                        name?: string;
+                    }
+                }
+                /**
+                 * Send the token pair from your backend. Both tokens must be from the same Link
+                 * grant under the referenced client. Supply a currently valid access token. Kernel
+                 * refreshes when needed after import and uses the expiry returned by Link for
+                 * subsequent tokens. Tokens are never returned in wallet responses, events, or
+                 * logs.
+                 */
+                interface Tokens {
+                    access_token: string;
+                    refresh_token: string;
+                }
+            }
+        }
+        /**
+         * AgentCard wallet. Omit provider_config to use Kernel-managed credentials, or
+         * select a customer-owned configuration. Mode (sandbox vs live) is determined by
+         * the selected credential; there is no per-item test flag. Without user_id,
+         * creation returns a hosted enrollment action and Kernel polls until the user
+         * connects. user_id may only reference a user already enrolled by a wallet in this
+         * organization under the same configuration.
+         */
+        interface AgentCardWalletVaultItemSpec {
+            provider: 'agentcard';
+            /**
+             * Select an AgentCard configuration. The wallet's configuration cannot be changed
+             * after creation.
+             */
+            provider_config?: AgentCardWalletVaultItemSpec.ProviderConfig;
+            user_id?: string;
+        }
+        namespace AgentCardWalletVaultItemSpec {
+            /**
+             * Select an AgentCard configuration. The wallet's configuration cannot be changed
+             * after creation.
+             */
+            interface ProviderConfig {
+                id?: string;
+                name?: string;
+            }
+        }
+    }
     interface CardVaultItemRequest {
         /**
          * Path param
@@ -524,6 +1150,6 @@ export declare namespace ItemUpsertParams {
     }
 }
 export declare namespace Items {
-    export { type AgentcardCheckoutAuthorization as AgentcardCheckoutAuthorization, type CardVaultItemSpec as CardVaultItemSpec, type CardVaultItemState as CardVaultItemState, type VaultCardAliases as VaultCardAliases, type VaultItem as VaultItem, type VaultItemAction as VaultItemAction, type VaultItemEvent as VaultItemEvent, type VaultPaymentMethod as VaultPaymentMethod, type WalletVaultItemSpec as WalletVaultItemSpec, type WalletVaultItemState as WalletVaultItemState, type ItemListResponse as ItemListResponse, type ItemEventsResponse as ItemEventsResponse, type ItemRetrieveParams as ItemRetrieveParams, type ItemUpdateParams as ItemUpdateParams, type ItemDeleteParams as ItemDeleteParams, type ItemEventsParams as ItemEventsParams, type ItemPerformOperationParams as ItemPerformOperationParams, type ItemUpsertParams as ItemUpsertParams, };
+    export { type AgentcardCheckoutAuthorization as AgentcardCheckoutAuthorization, type AgentcardCheckoutPreparation as AgentcardCheckoutPreparation, type AuthorizeVaultItemOperationRequest as AuthorizeVaultItemOperationRequest, type CardVaultItemSpec as CardVaultItemSpec, type CardVaultItemState as CardVaultItemState, type FillVaultItemOperationRequest as FillVaultItemOperationRequest, type FillVaultItemOperationResult as FillVaultItemOperationResult, type PrepareCheckoutVaultItemOperationRequest as PrepareCheckoutVaultItemOperationRequest, type VaultCardAliases as VaultCardAliases, type VaultCardFillField as VaultCardFillField, type VaultCheckoutContext as VaultCheckoutContext, type VaultFillFieldResult as VaultFillFieldResult, type VaultItem as VaultItem, type VaultItemAction as VaultItemAction, type VaultItemEvent as VaultItemEvent, type VaultItemOperationResponse as VaultItemOperationResponse, type VaultPaymentMethod as VaultPaymentMethod, type WalletVaultItemSpec as WalletVaultItemSpec, type WalletVaultItemState as WalletVaultItemState, type ItemListResponse as ItemListResponse, type ItemEventsResponse as ItemEventsResponse, type ItemRetrieveParams as ItemRetrieveParams, type ItemUpdateParams as ItemUpdateParams, type ItemDeleteParams as ItemDeleteParams, type ItemEventsParams as ItemEventsParams, type ItemPerformOperationParams as ItemPerformOperationParams, type ItemUpsertParams as ItemUpsertParams, };
 }
 //# sourceMappingURL=items.d.mts.map