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