diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 3200815c..87c62777 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "0.117.0" + ".": "0.118.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 09a70a0d..518c815f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## [0.118.0](https://github.com/kernel/kernel-node-sdk/compare/v0.117.0...v0.118.0) (2026-10-02) + + +### Features + +* Add a query filter to the vault list endpoint ([2a9d2e8](https://github.com/kernel/kernel-node-sdk/commit/2a9d2e844cb301f882f807a304b7fb6dc82ea077)) +* Add Kernel wallets backed by VGS agentic network tokens, with hosted card capture ([3fced64](https://github.com/kernel/kernel-node-sdk/commit/3fced64a6872afc6dd92f22713c61716cc75ecaa)) + ## [0.117.0](https://github.com/kernel/kernel-node-sdk/compare/v0.116.0...v0.117.0) (2026-10-02) diff --git a/api.md b/api.md index 6cd750a7..8bffeb49 100644 --- a/api.md +++ b/api.md @@ -513,9 +513,13 @@ Types: - CredentialVaultItemUpdateRequest - FillVaultItemOperationRequest - FillVaultItemOperationResult +- KernelCardState +- KernelCardVaultItemSpec - KernelCredentialVaultItemSpec - KernelCredentialVaultItemSpecInput - KernelCredentialVaultItemState +- KernelWalletState +- KernelWalletVaultItemSpec - OnePasswordCredentialAccountSpec - OnePasswordCredentialAccountState - OnePasswordCredentialVaultItemSpec diff --git a/package.json b/package.json index 1a5b569b..5ae446a3 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@onkernel/sdk", - "version": "0.117.0", + "version": "0.118.0", "description": "The official TypeScript library for the Kernel API", "author": "Kernel <>", "types": "dist/index.d.ts", diff --git a/src/resources/vaults/index.ts b/src/resources/vaults/index.ts index 69b544b1..831b6425 100644 --- a/src/resources/vaults/index.ts +++ b/src/resources/vaults/index.ts @@ -26,9 +26,13 @@ export { type CredentialVaultItemUpdateRequest, type FillVaultItemOperationRequest, type FillVaultItemOperationResult, + type KernelCardState, + type KernelCardVaultItemSpec, type KernelCredentialVaultItemSpec, type KernelCredentialVaultItemSpecInput, type KernelCredentialVaultItemState, + type KernelWalletState, + type KernelWalletVaultItemSpec, type OnePasswordCredentialAccountSpec, type OnePasswordCredentialAccountState, type OnePasswordCredentialVaultItemSpec, diff --git a/src/resources/vaults/items.ts b/src/resources/vaults/items.ts index bdc632b6..050604a0 100644 --- a/src/resources/vaults/items.ts +++ b/src/resources/vaults/items.ts @@ -87,10 +87,13 @@ export class Items extends APIResource { /** * 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. + * child cards of a wallet. Deleting a connected Kernel wallet first blocks new + * payments on it, then removes its enrolled card. If that fails, the wallet is + * kept and keeps refusing payments; retry the deletion. 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 @@ -304,8 +307,8 @@ export type AgentcardPreparedProcessor = | 'adyen'; /** - * Authorize a Link card using its existing purchase specification. Use only after - * explicit user approval and when the item advertises authorize. Do not + * 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. */ @@ -318,7 +321,8 @@ export interface AuthorizeVaultItemOperationRequest { */ export type CardVaultItemSpec = | CardVaultItemSpec.LinkCardVaultItemSpec - | CardVaultItemSpec.AgentCardCardVaultItemSpec; + | CardVaultItemSpec.AgentCardCardVaultItemSpec + | KernelCardVaultItemSpec; export namespace CardVaultItemSpec { /** @@ -462,7 +466,10 @@ export namespace CardVaultItemSpec { * Issued Link cards retain encrypted card material for the fill operation. Link * cards do not expose aliases or support egress substitution. */ -export type CardVaultItemState = CardVaultItemState.LinkCardState | CardVaultItemState.AgentCardCardState; +export type CardVaultItemState = + | CardVaultItemState.LinkCardState + | CardVaultItemState.AgentCardCardState + | KernelCardState; export namespace CardVaultItemState { /** @@ -501,6 +508,11 @@ export namespace CardVaultItemState { last4?: string; + /** + * Last four digits of the network token presented to the merchant. + */ + token_last4?: string; + [k: string]: string | undefined; } } @@ -559,6 +571,11 @@ export namespace CardVaultItemState { last4?: string; + /** + * Last four digits of the network token presented to the merchant. + */ + token_last4?: string; + [k: string]: string | undefined; } } @@ -1015,11 +1032,11 @@ export interface CredentialVaultItemUpdateRequest { } /** - * Fill selected fields from one ready credential or ready, unexpired Link 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. + * 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. @@ -1035,9 +1052,10 @@ export interface CredentialVaultItemUpdateRequest { * * 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 cards - * use fill for browser checkout and do not expose aliases or support egress - * substitution. Do not automatically retry a failed or indeterminate operation. + * 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. Do not automatically retry 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 @@ -1089,6 +1107,98 @@ export interface FillVaultItemOperationResult { type: 'fill'; } +/** + * A ready Kernel card retains its encrypted network token and one-time code for + * the fill operation until the item's expires_at. Fill and submit checkout before + * then. Visa cards can be enrolled, but Visa purchases are not yet supported and + * authorize returns 400; supported Mastercard purchases need no cardholder + * approval. masks.last4 is the enrolled card's last four digits; masks.token_last4 + * is the network token's last four digits shown to the merchant. Kernel cards do + * not expose aliases or support egress substitution. Kernel does not observe + * whether the merchant charged the card. + */ +export interface KernelCardState { + provider: 'kernel'; + + /** + * recovery_required means issuing the one-time code has an unresolved outcome. + * Kernel never issues another code for the item automatically, and the item cannot + * be deleted or replaced until the original attempt is reconciled with support. + * When status_reason says the provider refused retrieval before acceptance, no + * code was issued and a later read retries. + */ + status: + | 'requested' + | 'pending_authorization' + | 'ready' + | 'consumed' + | 'expired' + | 'declined' + | 'recovery_required'; + + /** + * Informational registrable domain. Fill is locked to merchant_url's exact origin. + */ + domains?: Array; + + masks?: KernelCardState.Masks; + + status_reason?: string; +} + +export namespace KernelCardState { + export interface Masks { + brand?: string; + + last4?: string; + + /** + * Last four digits of the network token presented to the merchant. + */ + token_last4?: string; + + [k: string]: string | undefined; + } +} + +/** + * One live purchase with a Kernel-enrolled card. Authorization obtains an agentic + * network token number, expiry and one-time 3-digit code. They are stored + * encrypted for the fill operation, which types them only on merchant_url's + * origin; the merchant's own checkout submits the payment. The one-time code is + * valid until the item's expires_at; fill and submit checkout before then. Visa + * cards can be enrolled, but Visa purchases are not yet supported: authorize + * returns 400. Supported Mastercard purchases need no cardholder approval. Card + * updates are not supported; delete and create a new item instead. + */ +export interface KernelCardVaultItemSpec { + /** + * Integer amount in minor currency units (at most 50000), bound to the one-time + * code. + */ + amount: number; + + /** + * ISO 4217 code. Supported: aud, brl, cad, chf, czk, dkk, eur, gbp, hkd, inr, jpy, + * krw, mxn, nok, nzd, pln, sek, sgd, usd, zar. + */ + currency: string; + + merchant_name: string; + + /** + * Merchant checkout URL. Fill is allowed only on this URL's origin. + */ + merchant_url: string; + + provider: 'kernel'; + + /** + * Key of the Kernel wallet item whose enrolled card pays. + */ + wallet: string; +} + export interface KernelCredentialVaultItemSpec { /** * Ordered field definitions rendered in this order by credential collection forms. @@ -1145,6 +1255,34 @@ export interface KernelCredentialVaultItemState { status: 'pending_collection' | 'ready'; } +export interface KernelWalletState { + provider: 'kernel'; + + /** + * pending_authorization asks the cardholder to use the card_enrollment action. + * connected is ready for supported purchases. reconnect_required asks the + * cardholder to use a new card_enrollment action after an uncertain enrollment was + * safely removed. degraded means the enrollment outcome is unknown and the wallet + * must be deleted before adding another card. + */ + status: 'pending_authorization' | 'connected' | 'reconnect_required' | 'degraded'; + + status_reason?: string; +} + +/** + * One card Kernel enrolls for Visa or Mastercard agentic network tokens using + * Kernel-managed credentials. Creation returns a card_enrollment action: the + * cardholder enters the card and their email on a Kernel-hosted page, then Kernel + * enrolls the securely stored card. The card number never reaches Kernel. The + * connected wallet's payment_methods expansion lists the enrolled card. Visa cards + * can be enrolled, but Visa purchases are not yet supported: authorize + * returns 400. + */ +export interface KernelWalletVaultItemSpec { + provider: 'kernel'; +} + export interface OnePasswordCredentialAccountSpec { authorization: OnePasswordCredentialAccountSpec.Authorization; @@ -2156,7 +2294,8 @@ export interface VaultWebmcpBinding { */ export type WalletVaultItemSpec = | WalletVaultItemSpec.LinkWalletVaultItemSpec - | WalletVaultItemSpec.AgentCardWalletVaultItemSpec; + | WalletVaultItemSpec.AgentCardWalletVaultItemSpec + | KernelWalletVaultItemSpec; export namespace WalletVaultItemSpec { export interface LinkWalletVaultItemSpec { @@ -2238,7 +2377,8 @@ export namespace WalletVaultItemSpec { export type WalletVaultItemState = | WalletVaultItemState.LinkWalletState - | WalletVaultItemState.AgentCardWalletState; + | WalletVaultItemState.AgentCardWalletState + | KernelWalletState; export namespace WalletVaultItemState { export interface LinkWalletState { @@ -2730,7 +2870,8 @@ export declare namespace ItemUpsertParams { */ spec: | WalletVaultItemRequest.LinkWalletVaultItemRequestSpec - | WalletVaultItemRequest.AgentCardWalletVaultItemSpec; + | WalletVaultItemRequest.AgentCardWalletVaultItemSpec + | KernelWalletVaultItemSpec; /** * Body param @@ -2964,9 +3105,13 @@ export declare namespace Items { type CredentialVaultItemUpdateRequest as CredentialVaultItemUpdateRequest, type FillVaultItemOperationRequest as FillVaultItemOperationRequest, type FillVaultItemOperationResult as FillVaultItemOperationResult, + type KernelCardState as KernelCardState, + type KernelCardVaultItemSpec as KernelCardVaultItemSpec, type KernelCredentialVaultItemSpec as KernelCredentialVaultItemSpec, type KernelCredentialVaultItemSpecInput as KernelCredentialVaultItemSpecInput, type KernelCredentialVaultItemState as KernelCredentialVaultItemState, + type KernelWalletState as KernelWalletState, + type KernelWalletVaultItemSpec as KernelWalletVaultItemSpec, type OnePasswordCredentialAccountSpec as OnePasswordCredentialAccountSpec, type OnePasswordCredentialAccountState as OnePasswordCredentialAccountState, type OnePasswordCredentialVaultItemSpec as OnePasswordCredentialVaultItemSpec, diff --git a/src/resources/vaults/vaults.ts b/src/resources/vaults/vaults.ts index 57c1b4bb..284cd6eb 100644 --- a/src/resources/vaults/vaults.ts +++ b/src/resources/vaults/vaults.ts @@ -36,9 +36,13 @@ import { ItemUpdateParams, ItemUpsertParams, Items, + KernelCardState, + KernelCardVaultItemSpec, KernelCredentialVaultItemSpec, KernelCredentialVaultItemSpecInput, KernelCredentialVaultItemState, + KernelWalletState, + KernelWalletVaultItemSpec, OnePasswordCredentialAccountSpec, OnePasswordCredentialAccountState, OnePasswordCredentialVaultItemSpec, @@ -106,9 +110,11 @@ export class Vaults extends APIResource { } /** - * 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. + * Unresolved payment operations block deletion. Deleting a connected Kernel wallet + * first blocks new payments on it, then removes its enrolled card. If that fails, + * the wallet is kept and keeps refusing payments; retry the 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 @@ -154,7 +160,12 @@ export interface Vault { updated_at: string; } -export interface VaultListParams extends OffsetPaginationParams {} +export interface VaultListParams extends OffsetPaginationParams { + /** + * Case-insensitive substring match against vault name. IDs match by exact value. + */ + query?: string; +} export interface VaultUpsertParams { /** @@ -199,9 +210,13 @@ export declare namespace Vaults { type CredentialVaultItemUpdateRequest as CredentialVaultItemUpdateRequest, type FillVaultItemOperationRequest as FillVaultItemOperationRequest, type FillVaultItemOperationResult as FillVaultItemOperationResult, + type KernelCardState as KernelCardState, + type KernelCardVaultItemSpec as KernelCardVaultItemSpec, type KernelCredentialVaultItemSpec as KernelCredentialVaultItemSpec, type KernelCredentialVaultItemSpecInput as KernelCredentialVaultItemSpecInput, type KernelCredentialVaultItemState as KernelCredentialVaultItemState, + type KernelWalletState as KernelWalletState, + type KernelWalletVaultItemSpec as KernelWalletVaultItemSpec, type OnePasswordCredentialAccountSpec as OnePasswordCredentialAccountSpec, type OnePasswordCredentialAccountState as OnePasswordCredentialAccountState, type OnePasswordCredentialVaultItemSpec as OnePasswordCredentialVaultItemSpec, diff --git a/src/version.ts b/src/version.ts index d3116d4a..23136063 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '0.117.0'; // x-release-please-version +export const VERSION = '0.118.0'; // x-release-please-version diff --git a/tests/api-resources/vaults/vaults.test.ts b/tests/api-resources/vaults/vaults.test.ts index 33b899eb..7e94d822 100644 --- a/tests/api-resources/vaults/vaults.test.ts +++ b/tests/api-resources/vaults/vaults.test.ts @@ -36,7 +36,14 @@ describe('resource vaults', () => { test.skip('list: request options and params are passed correctly', async () => { // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error await expect( - client.vaults.list({ limit: 1, offset: 0 }, { path: '/_stainless_unknown_path' }), + client.vaults.list( + { + limit: 1, + offset: 0, + query: 'query', + }, + { path: '/_stainless_unknown_path' }, + ), ).rejects.toThrow(Kernel.NotFoundError); });