@onkernel/sdk 0.99.0 → 0.101.0

package/src/resources/vaults/items.ts

@@ -14,6 +14,13 @@ export 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> {
     const { id_or_name, ...query } = params;
@@ -21,7 +28,31 @@ export class Items extends APIResource {
   }
 
   /**
-   * 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> {
     const { id_or_name, ...body } = params;
@@ -30,13 +61,29 @@ export class Items extends APIResource {
 
   /**
    * 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> {
     return this._client.get(path`/vaults/${idOrName}/items`, options);
   }
 
   /**
-   * Delete a vault item and invalidate its secret value
+   * Unresolved payment operations block deletion, including operations on child
+   * cards of a wallet. Reconcile the original attempt with the provider or support
+   * first; 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> {
     const { id_or_name } = params;
@@ -48,6 +95,14 @@ export class Items extends APIResource {
 
   /**
    * 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> {
     const { id_or_name, ...query } = params;
@@ -57,7 +112,20 @@ export class Items extends APIResource {
   /**
    * 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.
+   * may call an external provider and return updated state. Link cards advertise
+   * authorize. AgentCard cards are created with PUT and request approval when their
+   * aliases are used at checkout; they do not expose this operation. If
+   * spend-request creation is rate limited, returns HTTP 429 with code
+   * `spend_request_rate_limited`; stop and back off before retrying.
+   *
+   * @example
+   * ```ts
+   * const vaultItem =
+   *   await client.vaults.items.performOperation('key', {
+   *     id_or_name: 'id_or_name',
+   *     type: 'authorize',
+   *   });
+   * ```
    */
   performOperation(
     key: string,
@@ -69,7 +137,21 @@ export class Items extends APIResource {
   }
 
   /**
-   * 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> {
     const { id_or_name, ...body } = params;
@@ -142,14 +224,16 @@ export interface AgentcardCheckoutAuthorization {
 }
 
 /**
- * AgentCard reusable card. Each checkout creates an approval-gated authorization
- * for spec.merchant / spec.amount. The card stays ready after each authorization.
+ * Live payment card. Test-mode card creation is not supported.
  */
 export type CardVaultItemSpec =
   | CardVaultItemSpec.LinkCardVaultItemSpec
   | CardVaultItemSpec.AgentCardCardVaultItemSpec;
 
 export namespace CardVaultItemSpec {
+  /**
+   * Live payment card. Test-mode card creation is not supported.
+   */
   export interface LinkCardVaultItemSpec {
     /**
      * Integer amount in minor currency units.
@@ -173,12 +257,6 @@ export namespace CardVaultItemSpec {
 
     provider: 'link';
 
-    /**
-     * Whether Link should return test credentials instead of a live payment
-     * credential.
-     */
-    test: boolean;
-
     /**
      * Wallet item key used to mint this card.
      */
@@ -243,8 +321,9 @@ export namespace CardVaultItemSpec {
   }
 
   /**
-   * AgentCard reusable card. Each checkout creates an approval-gated authorization
-   * for spec.merchant / spec.amount. The card stays ready after each authorization.
+   * AgentCard reusable live payment card. Test-mode card creation is not supported.
+   * Each checkout creates an approval-gated authorization for spec.merchant /
+   * spec.amount. The card stays ready after each authorization.
    */
   export interface AgentCardCardVaultItemSpec {
     /**
@@ -280,7 +359,21 @@ export namespace CardVaultItemState {
   export 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;
 
@@ -304,7 +397,13 @@ export namespace CardVaultItemState {
   export interface AgentCardCardState {
     provider: 'agentcard';
 
-    status: 'requested' | 'ready' | 'pending_approval' | 'degraded';
+    /**
+     * recovery_required means the original checkout outcome is unresolved. Do not
+     * retry, delete, or replace it. Known authorization IDs may be reconciled through
+     * provider observations; otherwise contact the provider or support for manual
+     * reconciliation. It does not mean declined or expired.
+     */
+    status: 'requested' | 'ready' | 'pending_approval' | 'degraded' | 'recovery_required';
 
     aliases?: ItemsAPI.VaultCardAliases;
 
@@ -358,9 +457,12 @@ export 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;
 
@@ -424,8 +526,7 @@ export namespace VaultItem {
     key: string;
 
     /**
-     * AgentCard reusable card. Each checkout creates an approval-gated authorization
-     * for spec.merchant / spec.amount. The card stays ready after each authorization.
+     * Live payment card. Test-mode card creation is not supported.
      */
     spec: ItemsAPI.CardVaultItemSpec;
 
@@ -574,9 +675,12 @@ export 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
@@ -591,28 +695,73 @@ export namespace WalletVaultItemSpec {
 
   export namespace LinkWalletVaultItemSpec {
     export interface Authorization {
-      client: Authorization.Client;
+      client: Authorization.KernelManagedOAuthClient | Authorization.CustomerManagedOAuthClient;
 
       method: 'oauth';
     }
 
     export namespace Authorization {
-      export interface Client {
+      export interface KernelManagedOAuthClient {
         type: 'kernel_managed';
       }
+
+      export 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';
+      }
+
+      export 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.
+         */
+        export 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.
    */
   export interface AgentCardWalletVaultItemSpec {
     provider: 'agentcard';
 
+    /**
+     * Select an AgentCard configuration. The wallet's configuration cannot be changed
+     * after creation.
+     */
+    provider_config?: AgentCardWalletVaultItemSpec.ProviderConfig;
+
     user_id?: string;
   }
+
+  export namespace AgentCardWalletVaultItemSpec {
+    /**
+     * Select an AgentCard configuration. The wallet's configuration cannot be changed
+     * after creation.
+     */
+    export interface ProviderConfig {
+      id?: string;
+
+      name?: string;
+    }
+  }
 }
 
 export type WalletVaultItemState =
@@ -672,9 +821,7 @@ export interface ItemUpdateParams {
   id_or_name: string;
 
   /**
-   * Body param: AgentCard reusable card. Each checkout creates an approval-gated
-   * authorization for spec.merchant / spec.amount. The card stays ready after each
-   * authorization.
+   * Body param: Live payment card. Test-mode card creation is not supported.
    */
   spec: CardVaultItemSpec;
 }
@@ -724,11 +871,16 @@ 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
@@ -736,6 +888,150 @@ export declare namespace ItemUpsertParams {
     type: 'wallet';
   }
 
+  export namespace WalletVaultItemRequest {
+    export interface LinkWalletVaultItemRequestSpec {
+      /**
+       * Kernel starts and completes the user's Link authorization flow.
+       */
+      authorization:
+        | LinkWalletVaultItemRequestSpec.KernelManagedLinkAuthorizationInput
+        | LinkWalletVaultItemRequestSpec.ImportedLinkAuthorizationInput;
+
+      provider: 'link';
+    }
+
+    export namespace LinkWalletVaultItemRequestSpec {
+      /**
+       * Kernel starts and completes the user's Link authorization flow.
+       */
+      export interface KernelManagedLinkAuthorizationInput {
+        client: KernelManagedLinkAuthorizationInput.Client;
+
+        method: 'oauth';
+      }
+
+      export namespace KernelManagedLinkAuthorizationInput {
+        export 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.
+       */
+      export 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;
+      }
+
+      export namespace ImportedLinkAuthorizationInput {
+        export 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';
+        }
+
+        export 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.
+           */
+          export 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.
+         */
+        export 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.
+     */
+    export interface AgentCardWalletVaultItemSpec {
+      provider: 'agentcard';
+
+      /**
+       * Select an AgentCard configuration. The wallet's configuration cannot be changed
+       * after creation.
+       */
+      provider_config?: AgentCardWalletVaultItemSpec.ProviderConfig;
+
+      user_id?: string;
+    }
+
+    export namespace AgentCardWalletVaultItemSpec {
+      /**
+       * Select an AgentCard configuration. The wallet's configuration cannot be changed
+       * after creation.
+       */
+      export interface ProviderConfig {
+        id?: string;
+
+        name?: string;
+      }
+    }
+  }
+
   export interface CardVaultItemRequest {
     /**
      * Path param
@@ -743,9 +1039,7 @@ export declare namespace ItemUpsertParams {
     id_or_name: string;
 
     /**
-     * Body param: AgentCard reusable card. Each checkout creates an approval-gated
-     * authorization for spec.merchant / spec.amount. The card stays ready after each
-     * authorization.
+     * Body param: Live payment card. Test-mode card creation is not supported.
      */
     spec: CardVaultItemSpec;
 

package/src/resources/vaults/vaults.ts

@@ -34,6 +34,11 @@ export class Vaults extends APIResource {
 
   /**
    * Get a vault
+   *
+   * @example
+   * ```ts
+   * const vault = await client.vaults.retrieve('id_or_name');
+   * ```
    */
   retrieve(idOrName: string, options?: RequestOptions): APIPromise<Vault> {
     return this._client.get(path`/vaults/${idOrName}`, options);
@@ -41,6 +46,14 @@ export class Vaults extends APIResource {
 
   /**
    * List vaults in the current project
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const vault of client.vaults.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query: VaultListParams | null | undefined = {},
@@ -50,7 +63,14 @@ export class Vaults extends APIResource {
   }
 
   /**
-   * Delete a vault and invalidate its items
+   * Unresolved payment operations block deletion. Reconcile the original attempt
+   * with the provider or support first; deleting or recreating an item is not proof
+   * that a payment did not occur.
+   *
+   * @example
+   * ```ts
+   * await client.vaults.delete('id_or_name');
+   * ```
    */
   delete(idOrName: string, options?: RequestOptions): APIPromise<void> {
     return this._client.delete(path`/vaults/${idOrName}`, {
@@ -60,7 +80,16 @@ export class Vaults extends APIResource {
   }
 
   /**
-   * Create or retrieve a vault by immutable name
+   * Free organizations can store up to 3 non-deleted vaults across all projects.
+   * Paid plans and active trials have no vault cap. Retrieving an existing vault by
+   * name succeeds even at the limit.
+   *
+   * @example
+   * ```ts
+   * const vault = await client.vaults.upsert({
+   *   name: 'checkout',
+   * });
+   * ```
    */
   upsert(body: VaultUpsertParams, options?: RequestOptions): APIPromise<Vault> {
     return this._client.post('/vaults', { body, ...options });

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.99.0'; // x-release-please-version
+export const VERSION = '0.101.0'; // x-release-please-version

package/version.d.mts

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

package/version.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.mts","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,WAAW,CAAC"}
+{"version":3,"file":"version.d.mts","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,YAAY,CAAC"}

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.99.0";
+export declare const VERSION = "0.101.0";
 //# sourceMappingURL=version.d.ts.map

package/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,WAAW,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,YAAY,CAAC"}

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.99.0'; // x-release-please-version
+exports.VERSION = '0.101.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":";;;AAAa,QAAA,OAAO,GAAG,QAAQ,CAAC,CAAC,2BAA2B"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":";;;AAAa,QAAA,OAAO,GAAG,SAAS,CAAC,CAAC,2BAA2B"}

package/version.mjs

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

package/version.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"version.mjs","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,2BAA2B"}
+{"version":3,"file":"version.mjs","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,2BAA2B"}