@onkernel/sdk 0.142.0 → 0.144.0

package/src/resources/vaults/items.ts

@@ -157,7 +157,8 @@ export class Items extends APIResource {
    * a failure, an `unknown` outcome, or a transport error.
    *
    * Connected Kernel wallets may advertise add_payment_method, which returns a
-   * single-use hosted card_enrollment link for a card, and remove_payment_method,
+   * single-use hosted card_enrollment link for a card, or with enrollment server a
+   * single-use card_ingest URL for the card's issuer, and remove_payment_method,
    * which removes one card without affecting the others. Both operations require
    * vaults:write in addition to vaults:use on the vault for scoped API keys, and
    * return 403 without both permissions.
@@ -215,22 +216,32 @@ export class Items extends APIResource {
 }
 
 /**
- * Start hosted enrollment of a card in a connected Kernel wallet, including its
- * first card, only when the wallet advertises add_payment_method. Returns a new
- * payment method in pending_enrollment with a single-use card_enrollment URL for
- * the cardholder. Card details go directly to the card vault and are never
- * accepted by this API. Each call creates a separate link that expires after 30
- * minutes; a failed or expired enrollment does not affect the wallet's other
- * payment methods. Scoped API keys require vaults:write in addition to vaults:use
- * on this vault; otherwise the operation returns 403.
+ * Start enrollment of a card in a connected Kernel wallet, including its first
+ * card, only when the wallet advertises add_payment_method. Returns a new payment
+ * method in pending_enrollment with a single-use action. Card details go directly
+ * to the card vault and are never accepted by this API. With enrollment hosted
+ * (the default) the action is a card_enrollment URL for the cardholder, which
+ * expires after 30 minutes. With enrollment server the action is a card_ingest URL
+ * that the card's issuer posts the card to from its backend, which expires after 5
+ * minutes; server enrollment returns 409 when it is not configured for the
+ * organization's card backend. A failed or expired enrollment does not affect the
+ * wallet's other payment methods. Scoped API keys require vaults:write in addition
+ * to vaults:use on this vault; otherwise the operation returns 403.
  */
 export interface AddPaymentMethodVaultItemOperationRequest {
   type: 'add_payment_method';
+
+  /**
+   * hosted returns a card_enrollment link for the cardholder. server returns a
+   * card_ingest URL for the card's issuer to post the card to server to server.
+   */
+  enrollment?: 'hosted' | 'server';
 }
 
 /**
- * The payment method created in pending_enrollment. Deliver action.url to the
- * cardholder; it is a single-use capability and must not be logged. Observe
+ * The payment method created in pending_enrollment. Deliver a card_enrollment
+ * action.url to the cardholder; it is a single-use capability and must not be
+ * logged. A card_ingest action.url is posted to by the card's issuer. Observe
  * completion through the wallet's payment_methods expansion.
  */
 export interface AddPaymentMethodVaultItemOperationResult {
@@ -3835,16 +3846,28 @@ export interface VaultPaymentMethod {
    */
   type: string;
 
+  /**
+   * The open enrollment of a pending payment method. card_enrollment is a single-use
+   * hosted link for the cardholder. card_ingest is a single-use URL on a Kernel
+   * ingest hostname served by the card vault, which the card's issuer posts the card
+   * to from its backend; Kernel never receives the card number or CVC.
+   */
   action?: VaultPaymentMethod.Action;
 
   /**
-   * Expiry of a pending enrollment link.
+   * Expiry of a pending enrollment link or ingest URL.
    */
   expires_at?: string;
 
   /**
-   * Kernel wallets only. pending_enrollment means a card_enrollment link is open;
-   * active means the card is stored and can pay when
+   * Kernel wallets only. The issuer's reference for a card it pushed with a
+   * card_ingest URL.
+   */
+  issuer_reference?: string;
+
+  /**
+   * Kernel wallets only. pending_enrollment means a card_enrollment link or
+   * card_ingest URL is open; active means the card is stored and can pay when
    * capabilities.single_use_card.eligible is true; removal_pending means removal
    * started but the provider outcome is unknown, so retry remove_payment_method;
    * recovery_required means either an enrollment outcome is unknown (remove the
@@ -3855,6 +3878,12 @@ export interface VaultPaymentMethod {
   status?: 'pending_enrollment' | 'active' | 'removal_pending' | 'recovery_required';
 
   status_reason?: string;
+
+  /**
+   * Kernel wallets only. When a card pushed with a card_ingest URL stops being
+   * usable, as its issuer set.
+   */
+  valid_until?: string;
 }
 
 export namespace VaultPaymentMethod {
@@ -3882,15 +3911,21 @@ export namespace VaultPaymentMethod {
     last4?: string;
   }
 
+  /**
+   * The open enrollment of a pending payment method. card_enrollment is a single-use
+   * hosted link for the cardholder. card_ingest is a single-use URL on a Kernel
+   * ingest hostname served by the card vault, which the card's issuer posts the card
+   * to from its backend; Kernel never receives the card number or CVC.
+   */
   export interface Action {
-    name: 'card_enrollment';
+    name: 'card_enrollment' | 'card_ingest';
 
     url: string;
 
     /**
      * Secret bearer capability for embedded card capture with @onkernel/vault-react.
-     * Present only for Kernel wallets; never for AgentCard. Treat it like the
-     * enrollment URL and do not log or persist it in browser storage.
+     * Present only on card_enrollment for Kernel wallets; never for AgentCard. Treat
+     * it like the enrollment URL and do not log or persist it in browser storage.
      */
     capture_token?: string;
   }
@@ -3918,30 +3953,43 @@ export interface VaultWebmcpBinding {
 }
 
 /**
- * The card's aliases in the customer's VGS vault, its expiry and last four digits.
- * Write-only: stored encrypted and never returned in the item, its events or logs.
- * A repeated PUT with the same key must send the same card.
+ * The card supplied to a purchase, as aliases in the customer's VGS vault. With
+ * card_mode full it is a whole card: a persistent alias of its number, a freshly
+ * collected volatile alias of its security code, its expiry and its last four
+ * digits. With card_mode cvc_only it is a CVC alias alone, because the merchant
+ * holds the rest on file. pan_alias, exp_month, exp_year and last4 are required
+ * with card_mode full and rejected with card_mode cvc_only. Write-only: stored
+ * encrypted and never returned in the item, its events or logs. A repeated PUT
+ * with the same key must send the same card.
  */
 export interface VgsCardInput {
   /**
    * A volatile alias of a freshly collected security code in the customer's vault.
-   * It must still exist when authorize runs.
+   * It must still exist when authorize runs. Required in both modes.
    */
   cvc_alias: string;
 
-  exp_month: number;
+  /**
+   * Required with card_mode full, rejected with card_mode cvc_only.
+   */
+  exp_month?: number;
 
-  exp_year: number;
+  /**
+   * Required with card_mode full, rejected with card_mode cvc_only.
+   */
+  exp_year?: number;
 
   /**
-   * The card number's last four digits, checked against the revealed alias.
+   * The card number's last four digits, checked against the revealed alias. Required
+   * with card_mode full, rejected with card_mode cvc_only.
    */
-  last4: string;
+  last4?: string;
 
   /**
-   * A persistent alias of the card number in the customer's vault.
+   * A persistent alias of the card number in the customer's vault. Required with
+   * card_mode full, rejected with card_mode cvc_only.
    */
-  pan_alias: string;
+  pan_alias?: string;
 }
 
 /**
@@ -3991,17 +4039,24 @@ export namespace VgsCardState {
 }
 
 /**
- * One live purchase with a card in the customer's VGS vault. authorize reveals
- * card.pan_alias and card.cvc_alias through Kernel's VGS outbound proxy, which
- * replaces both with aliases in Kernel's vault before they reach Kernel; Kernel
- * never receives the card number or security code. The card is then ready with no
- * further approval, until expires_at, by default five minutes after authorize.
- * fill types Kernel's aliases on merchant_url's origin, and Kernel's VGS proxy
- * replaces them with the card's details when the browser submits checkout. An
- * expired card requires a new purchase with a freshly collected CVC alias. The
- * amount and merchant are recorded but do not restrict payment requests sent by
- * the browser. Card updates are not supported; delete and create a new item
- * instead.
+ * One live purchase with a card in the customer's VGS vault. With card_mode full,
+ * authorize reveals card.pan_alias and card.cvc_alias through Kernel's VGS
+ * outbound proxy; with card_mode cvc_only, for a card the merchant already holds
+ * on file whose checkout page asks only for the security code, it reveals
+ * card.cvc_alias alone. The proxy replaces each revealed value with an alias in
+ * Kernel's vault before it reaches Kernel; Kernel never receives the card number
+ * or security code. The card is then ready with no further approval, until
+ * expires_at, by default five minutes after authorize. fill types Kernel's aliases
+ * on merchant_url's origin, and Kernel's VGS proxy replaces them with the card's
+ * details when the browser submits checkout; a cvc_only card fills only the cvc
+ * field, and reports no masks because it has no last4 to verify. A cvc_only card's
+ * payment window routes all of the browser's egress through Kernel's VGS outbound
+ * proxy, exactly as widely as a full card's: while it is open the proxy reveals
+ * the card's aliases to any destination the browser sends them to, not only the
+ * security code. An expired card requires a new purchase with a freshly collected
+ * CVC alias. The amount and merchant are recorded but do not restrict payment
+ * requests sent by the browser. Card updates are not supported; delete and create
+ * a new item instead.
  */
 export interface VgsCardVaultItemSpec {
   /**
@@ -4033,6 +4088,15 @@ export interface VgsCardVaultItemSpec {
    * Required when creating the card. Never returned.
    */
   card?: VgsCardInput;
+
+  /**
+   * Which card this purchase supplies, and the only part of it a read returns. full
+   * is a whole card from the customer's vault. cvc_only is a card the merchant
+   * already holds on file, whose checkout page asks for nothing but the security
+   * code. It must match spec.card: a full card that is missing pan_alias is rejected
+   * rather than treated as cvc_only. Omit it for full, which a read also omits.
+   */
+  card_mode?: 'full' | 'cvc_only';
 }
 
 export interface VgsWalletState {
@@ -4894,6 +4958,13 @@ export declare namespace ItemPerformOperationParams {
      * Body param
      */
     type: 'add_payment_method';
+
+    /**
+     * Body param: hosted returns a card_enrollment link for the cardholder. server
+     * returns a card_ingest URL for the card's issuer to post the card to server to
+     * server.
+     */
+    enrollment?: 'hosted' | 'server';
   }
 
   export interface RemovePaymentMethodVaultItemOperationRequest {

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.142.0'; // x-release-please-version
+export const VERSION = '0.144.0'; // x-release-please-version

package/version.d.mts

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

package/version.d.ts

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

package/version.mjs

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