diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 3c1df308..7c57a5df 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "0.98.0" + ".": "0.99.0" } diff --git a/.stats.yml b/.stats.yml index a867372d..5fe5772a 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1 +1 @@ -configured_endpoints: 147 +configured_endpoints: 158 diff --git a/CHANGELOG.md b/CHANGELOG.md index a3e18e2b..21991d46 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## [0.99.0](https://github.com/kernel/kernel-node-sdk/compare/v0.98.0...v0.99.0) (2026-09-04) + + +### Features + +* Expose OTLP destination delivery health ([c393d37](https://github.com/kernel/kernel-node-sdk/commit/c393d37d72171e841f1ebf8ce0a9720f5ae271d8)) +* Repair Vault SDK custom-code seals ([c6a1099](https://github.com/kernel/kernel-node-sdk/commit/c6a1099b453b25a67f54154fadec6f5b0586b472)) + ## [0.98.0](https://github.com/kernel/kernel-node-sdk/compare/v0.97.0...v0.98.0) (2026-09-02) diff --git a/api.md b/api.md index 9f4e5a6c..4093cf9b 100644 --- a/api.md +++ b/api.md @@ -108,6 +108,7 @@ Types: - BrowserUsage - Profile - Tags +- VaultReference - BrowserCreateResponse - BrowserRetrieveResponse - BrowserUpdateResponse @@ -432,6 +433,46 @@ Methods: - client.browserPools.flush(idOrName) -> void - client.browserPools.release(idOrName, { ...params }) -> void +# Vaults + +Types: + +- Vault + +Methods: + +- client.vaults.retrieve(idOrName) -> Vault +- client.vaults.list({ ...params }) -> VaultsOffsetPagination +- client.vaults.delete(idOrName) -> void +- client.vaults.upsert({ ...params }) -> Vault + +## Items + +Types: + +- AgentcardCheckoutAuthorization +- CardVaultItemSpec +- CardVaultItemState +- VaultCardAliases +- VaultItem +- VaultItemAction +- VaultItemEvent +- VaultPaymentMethod +- WalletVaultItemSpec +- WalletVaultItemState +- ItemListResponse +- ItemEventsResponse + +Methods: + +- client.vaults.items.retrieve(key, { ...params }) -> VaultItem +- client.vaults.items.update(key, { ...params }) -> VaultItem +- client.vaults.items.list(idOrName) -> ItemListResponse +- client.vaults.items.delete(key, { ...params }) -> void +- client.vaults.items.events(key, { ...params }) -> ItemEventsResponse +- client.vaults.items.performOperation(key, { ...params }) -> VaultItem +- client.vaults.items.upsert(key, { ...params }) -> VaultItem + # Credentials Types: diff --git a/package.json b/package.json index 1708299a..bda9379c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@onkernel/sdk", - "version": "0.98.0", + "version": "0.99.0", "description": "The official TypeScript library for the Kernel API", "author": "Kernel <>", "types": "dist/index.d.ts", diff --git a/src/client.ts b/src/client.ts index c66a88d0..20013d6e 100644 --- a/src/client.ts +++ b/src/client.ts @@ -168,6 +168,7 @@ import { Browsers, Profile, Tags, + VaultReference, } from './resources/browsers/browsers'; import { Analysis, @@ -202,6 +203,13 @@ import { UpdateProjectRequest, } from './resources/projects/projects'; import { Telemetry } from './resources/telemetry/telemetry'; +import { + Vault, + VaultListParams, + VaultUpsertParams, + Vaults, + VaultsOffsetPagination, +} from './resources/vaults/vaults'; import { type Fetch } from './internal/builtin-types'; import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers'; import { FinalRequestOptions, RequestOptions } from './internal/request-options'; @@ -1059,6 +1067,7 @@ export class Kernel { * Create and manage browser pools for acquiring and releasing browsers. */ browserPools: API.BrowserPools = new API.BrowserPools(this); + vaults: API.Vaults = new API.Vaults(this); /** * Create and manage credentials for authentication. */ @@ -1096,6 +1105,7 @@ Kernel.Telemetry = Telemetry; Kernel.Proxies = Proxies; Kernel.Extensions = Extensions; Kernel.BrowserPools = BrowserPools; +Kernel.Vaults = Vaults; Kernel.Credentials = Credentials; Kernel.Projects = Projects; Kernel.Organization = Organization; @@ -1188,6 +1198,7 @@ export declare namespace Kernel { type BrowserUsage as BrowserUsage, type Profile as Profile, type Tags as Tags, + type VaultReference as VaultReference, type BrowserCreateResponse as BrowserCreateResponse, type BrowserRetrieveResponse as BrowserRetrieveResponse, type BrowserUpdateResponse as BrowserUpdateResponse, @@ -1252,6 +1263,14 @@ export declare namespace Kernel { type BrowserPoolReleaseParams as BrowserPoolReleaseParams, }; + export { + Vaults as Vaults, + type Vault as Vault, + type VaultsOffsetPagination as VaultsOffsetPagination, + type VaultListParams as VaultListParams, + type VaultUpsertParams as VaultUpsertParams, + }; + export { Credentials as Credentials, type CreateCredentialRequest as CreateCredentialRequest, diff --git a/src/resources/browser-pools.ts b/src/resources/browser-pools.ts index dc0ed128..e61cbc90 100644 --- a/src/resources/browser-pools.ts +++ b/src/resources/browser-pools.ts @@ -501,6 +501,17 @@ export interface BrowserPoolAcquireResponse { */ usage?: BrowsersAPI.BrowserUsage; + /** + * Whether final usage billing is still pending or complete. Only present for + * deleted sessions. + */ + usage_status?: 'pending' | 'ready'; + + /** + * Vaults linked when the browser session was created. + */ + vaults?: Array; + /** * Initial browser window size in pixels with optional refresh rate. If omitted, * image defaults apply (1920x1080@25). For GPU images, the default is diff --git a/src/resources/browsers/browsers.ts b/src/resources/browsers/browsers.ts index c1adfabc..cd3e2ca5 100644 --- a/src/resources/browsers/browsers.ts +++ b/src/resources/browsers/browsers.ts @@ -479,6 +479,15 @@ export interface Profile { */ export type Tags = { [key: string]: string }; +/** + * Reference to a project-scoped vault. Provide exactly one of id or name. + */ +export interface VaultReference { + id?: string; + + name?: string; +} + export interface BrowserCreateResponse { /** * Websocket URL for Chrome DevTools Protocol connections to the browser session @@ -622,6 +631,17 @@ export interface BrowserCreateResponse { */ usage?: BrowserUsage; + /** + * Whether final usage billing is still pending or complete. Only present for + * deleted sessions. + */ + usage_status?: 'pending' | 'ready'; + + /** + * Vaults linked when the browser session was created. + */ + vaults?: Array; + /** * Initial browser window size in pixels with optional refresh rate. If omitted, * image defaults apply (1920x1080@25). For GPU images, the default is @@ -782,6 +802,17 @@ export interface BrowserRetrieveResponse { */ usage?: BrowserUsage; + /** + * Whether final usage billing is still pending or complete. Only present for + * deleted sessions. + */ + usage_status?: 'pending' | 'ready'; + + /** + * Vaults linked when the browser session was created. + */ + vaults?: Array; + /** * Initial browser window size in pixels with optional refresh rate. If omitted, * image defaults apply (1920x1080@25). For GPU images, the default is @@ -942,6 +973,17 @@ export interface BrowserUpdateResponse { */ usage?: BrowserUsage; + /** + * Whether final usage billing is still pending or complete. Only present for + * deleted sessions. + */ + usage_status?: 'pending' | 'ready'; + + /** + * Vaults linked when the browser session was created. + */ + vaults?: Array; + /** * Initial browser window size in pixels with optional refresh rate. If omitted, * image defaults apply (1920x1080@25). For GPU images, the default is @@ -1102,6 +1144,17 @@ export interface BrowserListResponse { */ usage?: BrowserUsage; + /** + * Whether final usage billing is still pending or complete. Only present for + * deleted sessions. + */ + usage_status?: 'pending' | 'ready'; + + /** + * Vaults linked when the browser session was created. + */ + vaults?: Array; + /** * Initial browser window size in pixels with optional refresh rate. If omitted, * image defaults apply (1920x1080@25). For GPU images, the default is @@ -1270,6 +1323,12 @@ export interface BrowserCreateParams { */ timeout_seconds?: number; + /** + * Project-scoped vaults to link to the browser session. Links are immutable after + * creation. + */ + vaults?: Array; + /** * Initial browser window size in pixels with optional refresh rate. If omitted, * image defaults apply (1920x1080@25). For GPU images, the default is @@ -1657,6 +1716,7 @@ export declare namespace Browsers { type BrowserUsage as BrowserUsage, type Profile as Profile, type Tags as Tags, + type VaultReference as VaultReference, type BrowserCreateResponse as BrowserCreateResponse, type BrowserRetrieveResponse as BrowserRetrieveResponse, type BrowserUpdateResponse as BrowserUpdateResponse, diff --git a/src/resources/browsers/index.ts b/src/resources/browsers/index.ts index 7742988a..6b89a0a5 100644 --- a/src/resources/browsers/index.ts +++ b/src/resources/browsers/index.ts @@ -12,6 +12,7 @@ export { type BrowserUsage, type Profile, type Tags, + type VaultReference, type BrowserCreateResponse, type BrowserRetrieveResponse, type BrowserUpdateResponse, diff --git a/src/resources/config-registry/config-registry.ts b/src/resources/config-registry/config-registry.ts index 8e05c8c2..8ac23ee6 100644 --- a/src/resources/config-registry/config-registry.ts +++ b/src/resources/config-registry/config-registry.ts @@ -15,8 +15,8 @@ export class ConfigRegistry extends APIResource { analyses: AnalysesAPI.Analyses = new AnalysesAPI.Analyses(this._client); /** - * Lists unique domains previously analyzed by the selected project with their - * current domain-level recommendations. + * Lists unique exact targets previously analyzed by the selected project with the + * recommendation produced by each target's latest analysis. * * @example * ```ts @@ -431,22 +431,24 @@ export type RecommendationResult = Recommendation | NoRecommendation; export interface RecommendationSummary { /** - * ID of the most recently requested analysis for this domain. + * ID of the most recently requested analysis for this exact target. */ analysis_id: string; /** - * Lifecycle status of the most recently requested analysis for this domain. + * Lifecycle status of the most recently requested analysis for this exact target. */ analysis_status: 'running' | 'completed' | 'failed' | 'canceled'; /** - * Most recent time the selected project requested an analysis for this domain. + * Most recent time the selected project requested an analysis for this exact + * target. */ last_requested_at: string; /** - * Current domain-level recommendation. Null when no eligible knowledge exists. + * Recommendation produced by the latest analysis. Null when that analysis did not + * produce one. */ recommendation: Recommendation | null; @@ -456,13 +458,14 @@ export interface RecommendationSummary { recommended_config_label: string | null; /** - * Success rate for the recommended configuration. Null when no eligible knowledge - * exists. + * Success rate for the recommended configuration. Null when the latest analysis + * did not produce one. */ success_rate: number | null; /** - * Registrable domain previously analyzed by the selected project. + * Normalized exact target previously analyzed by the selected project, including + * scheme, host, port, and path. */ target: string; } @@ -500,8 +503,8 @@ export interface Target { export interface ConfigRegistryListParams extends OffsetPaginationParams { /** - * Case-insensitive domain search. Full URLs are reduced to their registrable - * domain. + * Case-insensitive substring search over normalized targets, including domain, + * subdomain, and path. */ search?: string; diff --git a/src/resources/index.ts b/src/resources/index.ts index fb5554a1..d1837dd1 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -50,6 +50,7 @@ export { type BrowserUsage, type Profile, type Tags, + type VaultReference, type BrowserCreateResponse, type BrowserRetrieveResponse, type BrowserUpdateResponse, @@ -179,3 +180,10 @@ export { type ProxyListResponsesOffsetPagination, } from './proxies'; export { Telemetry } from './telemetry/telemetry'; +export { + Vaults, + type Vault, + type VaultListParams, + type VaultUpsertParams, + type VaultsOffsetPagination, +} from './vaults/vaults'; diff --git a/src/resources/invocations.ts b/src/resources/invocations.ts index 34b690a9..0ba6cd88 100644 --- a/src/resources/invocations.ts +++ b/src/resources/invocations.ts @@ -561,6 +561,17 @@ export namespace InvocationListBrowsersResponse { */ usage?: BrowsersAPI.BrowserUsage; + /** + * Whether final usage billing is still pending or complete. Only present for + * deleted sessions. + */ + usage_status?: 'pending' | 'ready'; + + /** + * Vaults linked when the browser session was created. + */ + vaults?: Array; + /** * Initial browser window size in pixels with optional refresh rate. If omitted, * image defaults apply (1920x1080@25). For GPU images, the default is diff --git a/src/resources/telemetry/destinations.ts b/src/resources/telemetry/destinations.ts index 0c5b8ada..0fd62129 100644 --- a/src/resources/telemetry/destinations.ts +++ b/src/resources/telemetry/destinations.ts @@ -92,6 +92,13 @@ export type OtlpDestinationsOffsetPagination = OffsetPagination export interface OtlpDestination { id: string; + /** + * Failed deliveries since the last success, as observed by the relay process that + * wrote the latest outcome. Zero means the most recently recorded outcome + * succeeded. + */ + consecutive_failures: number; + created_at: string; /** @@ -116,6 +123,26 @@ export interface OtlpDestination { updated_at: string; description?: string; + + /** + * Sanitized class of the delivery failure recorded at `last_error_at`. It is + * retained after a later success, so its presence does not mean the destination is + * currently failing. Response bodies, endpoint URLs, credentials, and raw + * transport errors are never returned. + */ + last_error?: string; + + /** + * Timestamp of the most recent failed delivery. It is retained after a later + * success, so it can predate `last_export_at`. Read `consecutive_failures` to tell + * whether the destination is currently failing. + */ + last_error_at?: string; + + /** + * Timestamp of the most recent successful delivery. Moves only on success. + */ + last_export_at?: string; } export interface DestinationCreateParams { diff --git a/src/resources/vaults.ts b/src/resources/vaults.ts new file mode 100644 index 00000000..a89c5e13 --- /dev/null +++ b/src/resources/vaults.ts @@ -0,0 +1,3 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +export * from './vaults/index'; diff --git a/src/resources/vaults/index.ts b/src/resources/vaults/index.ts new file mode 100644 index 00000000..190af0eb --- /dev/null +++ b/src/resources/vaults/index.ts @@ -0,0 +1,30 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +export { + Items, + type AgentcardCheckoutAuthorization, + type CardVaultItemSpec, + type CardVaultItemState, + type VaultCardAliases, + type VaultItem, + type VaultItemAction, + type VaultItemEvent, + type VaultPaymentMethod, + type WalletVaultItemSpec, + type WalletVaultItemState, + type ItemListResponse, + type ItemEventsResponse, + type ItemRetrieveParams, + type ItemUpdateParams, + type ItemDeleteParams, + type ItemEventsParams, + type ItemPerformOperationParams, + type ItemUpsertParams, +} from './items'; +export { + Vaults, + type Vault, + type VaultListParams, + type VaultUpsertParams, + type VaultsOffsetPagination, +} from './vaults'; diff --git a/src/resources/vaults/items.ts b/src/resources/vaults/items.ts new file mode 100644 index 00000000..011cff6a --- /dev/null +++ b/src/resources/vaults/items.ts @@ -0,0 +1,780 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import { APIResource } from '../../core/resource'; +import * as ItemsAPI from './items'; +import { APIPromise } from '../../core/api-promise'; +import { buildHeaders } from '../../internal/headers'; +import { RequestOptions } from '../../internal/request-options'; +import { path } from '../../internal/utils/path'; + +export class Items extends APIResource { + /** + * The response advertises operations that are valid in the item's current state + * and live data that can be requested through `expand`. Read each operation's + * 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. + */ + retrieve(key: string, params: ItemRetrieveParams, options?: RequestOptions): APIPromise { + const { id_or_name, ...query } = params; + return this._client.get(path`/vaults/${id_or_name}/items/${key}`, { query, ...options }); + } + + /** + * Update a card specification before or between authorizations + */ + update(key: string, params: ItemUpdateParams, options?: RequestOptions): APIPromise { + const { id_or_name, ...body } = params; + return this._client.patch(path`/vaults/${id_or_name}/items/${key}`, { body, ...options }); + } + + /** + * List vault items without secret values + */ + list(idOrName: string, options?: RequestOptions): APIPromise { + return this._client.get(path`/vaults/${idOrName}/items`, options); + } + + /** + * Delete a vault item and invalidate its secret value + */ + delete(key: string, params: ItemDeleteParams, options?: RequestOptions): APIPromise { + const { id_or_name } = params; + return this._client.delete(path`/vaults/${id_or_name}/items/${key}`, { + ...options, + headers: buildHeaders([{ Accept: '*/*' }, options?.headers]), + }); + } + + /** + * List immutable audit events for a vault item + */ + events(key: string, params: ItemEventsParams, options?: RequestOptions): APIPromise { + const { id_or_name, ...query } = params; + return this._client.get(path`/vaults/${id_or_name}/items/${key}/events`, { query, ...options }); + } + + /** + * 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. + */ + performOperation( + key: string, + params: ItemPerformOperationParams, + options?: RequestOptions, + ): APIPromise { + const { id_or_name, ...body } = params; + return this._client.post(path`/vaults/${id_or_name}/items/${key}/operations`, { body, ...options }); + } + + /** + * Create or retrieve an identical vault item by immutable key + */ + upsert(key: string, params: ItemUpsertParams, options?: RequestOptions): APIPromise { + const { id_or_name, ...body } = params; + return this._client.put(path`/vaults/${id_or_name}/items/${key}`, { body, ...options }); + } +} + +/** + * The in-flight or most recent checkout authorization. Present while a checkout is + * pending approval and after it settles. + */ +export interface AgentcardCheckoutAuthorization { + id: string; + + amount_cents: number; + + created_at: string; + + currency: string; + + merchant: string; + + psp: string; + + status: 'awaiting_approval' | 'approved' | 'declined' | 'expired'; + + actual_cents?: number; + + /** + * Display amount shown on the approval screen. + */ + amount?: string; + + amount_authority?: 'display_only' | 'stripe_payment_intent'; + + amount_verified?: boolean; + + approval_url?: string; + + /** + * Browser session that submitted the checkout. + */ + browser_id?: string; + + charged_amount_cents?: number; + + charged_currency?: string; + + charged_kind?: 'captured' | 'authorized' | 'none'; + + expected_cents?: number; + + expires_at?: string; + + psp_error_code?: string; + + reason?: string; + + replay_attempted?: boolean; + + /** + * Whether the processor response was delivered to the browser. + */ + replay_delivered?: boolean; + + /** + * HTTP status of the replayed processor response. + */ + replay_status?: number; +} + +/** + * AgentCard reusable card. Each checkout creates an approval-gated authorization + * for spec.merchant / spec.amount. The card stays ready after each authorization. + */ +export type CardVaultItemSpec = + | CardVaultItemSpec.LinkCardVaultItemSpec + | CardVaultItemSpec.AgentCardCardVaultItemSpec; + +export namespace CardVaultItemSpec { + export interface LinkCardVaultItemSpec { + /** + * Integer amount in minor currency units. + */ + amount: number; + + context: string; + + currency: string; + + merchant_name: string; + + merchant_url: string; + + /** + * Payment-method ID returned by the referenced wallet's payment-method listing. + * The provider decides whether the selected funding method can satisfy the card + * request. + */ + payment_method_id: string; + + provider: 'link'; + + /** + * Whether Link should return test credentials instead of a live payment + * credential. + */ + test: boolean; + + /** + * Wallet item key used to mint this card. + */ + wallet: string; + + expires_at?: number; + + line_items?: Array; + + metadata?: { [key: string]: string }; + + totals?: Array; + } + + export namespace LinkCardVaultItemSpec { + export interface LineItem { + name: string; + + description?: string; + + image_url?: string; + + product_url?: string; + + quantity?: number; + + sku?: string; + + totals?: Array; + + /** + * Unit amount in minor currency units. + */ + unit_amount?: number; + + url?: string; + } + + export namespace LineItem { + export interface Total { + /** + * Total amount in minor currency units. + */ + amount: number; + + display_text: string; + + type: string; + } + } + + export interface Total { + /** + * Total amount in minor currency units. + */ + amount: number; + + display_text: string; + + type: string; + } + } + + /** + * AgentCard reusable card. Each checkout creates an approval-gated authorization + * for spec.merchant / spec.amount. The card stays ready after each authorization. + */ + export interface AgentCardCardVaultItemSpec { + /** + * Integer amount in minor currency units. + */ + amount: number; + + currency: string; + + /** + * Merchant name shown on the cardholder's approval screen. + */ + merchant: string; + + provider: 'agentcard'; + + /** + * Wallet item key used to authorize checkouts. + */ + wallet: string; + + /** + * AgentCard vaulted card to pay with. Omitted, the cardholder picks on the + * approval screen. + */ + card_id?: string; + } +} + +export type CardVaultItemState = CardVaultItemState.LinkCardState | CardVaultItemState.AgentCardCardState; + +export namespace CardVaultItemState { + export interface LinkCardState { + provider: 'link'; + + status: 'requested' | 'pending_authorization' | 'ready' | 'consumed' | 'expired' | 'declined'; + + aliases?: ItemsAPI.VaultCardAliases; + + domains?: Array; + + masks?: LinkCardState.Masks; + + status_reason?: string; + } + + export namespace LinkCardState { + export interface Masks { + brand?: string; + + last4?: string; + + [k: string]: string | undefined; + } + } + + export interface AgentCardCardState { + provider: 'agentcard'; + + status: 'requested' | 'ready' | 'pending_approval' | 'degraded'; + + aliases?: ItemsAPI.VaultCardAliases; + + /** + * The in-flight or most recent checkout authorization. Present while a checkout is + * pending approval and after it settles. + */ + authorization?: ItemsAPI.AgentcardCheckoutAuthorization; + + masks?: AgentCardCardState.Masks; + + status_reason?: string; + } + + export namespace AgentCardCardState { + export interface Masks { + brand?: string; + + last4?: string; + + [k: string]: string | undefined; + } + } +} + +export interface VaultCardAliases { + cvc: string; + + exp_month: string; + + exp_year: string; + + number: string; +} + +export type VaultItem = VaultItem.WalletVaultItem | VaultItem.CardVaultItem; + +export namespace VaultItem { + export interface WalletVaultItem { + id: string; + + available_expansions: Array; + + available_operations: Array; + + created_at: string; + + /** + * Immutable item key assigned when the item is created. + */ + 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. + */ + 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; + } + + export namespace WalletVaultItem { + /** + * Live data that can currently be requested by passing its type to the item GET + * expand parameter. + */ + export 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. + */ + export interface AvailableOperation { + description: string; + + type: 'authorize'; + } + + /** + * Live, non-persisted data requested through the item GET expand parameter. + */ + export interface Expanded { + payment_methods?: Array; + } + } + + export interface CardVaultItem { + id: string; + + available_expansions: Array; + + available_operations: Array; + + created_at: string; + + /** + * Immutable item key assigned when the item is created. + */ + key: string; + + /** + * AgentCard reusable card. Each checkout creates an approval-gated authorization + * for spec.merchant / spec.amount. The card stays ready after each authorization. + */ + spec: ItemsAPI.CardVaultItemSpec; + + state: ItemsAPI.CardVaultItemState; + + type: 'card'; + + updated_at: string; + + action?: ItemsAPI.VaultItemAction; + + expires_at?: string; + } + + export namespace CardVaultItem { + /** + * Live data that can currently be requested by passing its type to the item GET + * expand parameter. + */ + export 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. + */ + export interface AvailableOperation { + description: string; + + type: 'authorize'; + } + } +} + +export type VaultItemAction = + | VaultItemAction.LinkOAuthAction + | VaultItemAction.SpendApprovalAction + | VaultItemAction.PushApprovalAction + | VaultItemAction.CollectAction + | VaultItemAction.MfaAction + | VaultItemAction.EmbeddedCeremonyAction + | VaultItemAction.CardEnrollmentAction; + +export namespace VaultItemAction { + export interface LinkOAuthAction { + name: 'link_oauth'; + + url: string; + } + + export interface SpendApprovalAction { + name: 'spend_approval'; + + url: string; + } + + export interface PushApprovalAction { + name: 'push_approval'; + } + + export interface CollectAction { + name: 'collect'; + } + + export interface MfaAction { + name: 'mfa'; + } + + export interface EmbeddedCeremonyAction { + name: 'embedded_ceremony'; + } + + export interface CardEnrollmentAction { + name: 'card_enrollment'; + + url: string; + } +} + +export interface VaultItemEvent { + id: string; + + created_at: string; + + name: string; + + /** + * Browser session associated with the event, when applicable. + */ + browser_id?: string; + + data?: { [key: string]: unknown }; +} + +export interface VaultPaymentMethod { + id: string; + + /** + * Provider-reported advisory capabilities. A missing capability is unknown, not + * ineligible; only eligible=false is an explicit negative signal. + */ + capabilities: VaultPaymentMethod.Capabilities; + + display: VaultPaymentMethod.Display; + + is_default: boolean; + + /** + * Provider that issued this payment-method ID. + */ + provider: string; + + /** + * Provider-neutral payment-method type normalized to lowercase. + */ + type: string; +} + +export namespace VaultPaymentMethod { + /** + * Provider-reported advisory capabilities. A missing capability is unknown, not + * ineligible; only eligible=false is an explicit negative signal. + */ + export interface Capabilities { + single_use_card?: Capabilities.SingleUseCard; + } + + export namespace Capabilities { + export interface SingleUseCard { + eligible: boolean; + + reasons: Array; + } + } + + export interface Display { + brand?: string; + + label?: string; + + last4?: 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. + */ +export type WalletVaultItemSpec = + | WalletVaultItemSpec.LinkWalletVaultItemSpec + | WalletVaultItemSpec.AgentCardWalletVaultItemSpec; + +export namespace WalletVaultItemSpec { + export interface LinkWalletVaultItemSpec { + authorization: LinkWalletVaultItemSpec.Authorization; + + provider: 'link'; + } + + export namespace LinkWalletVaultItemSpec { + export interface Authorization { + client: Authorization.Client; + + method: 'oauth'; + } + + export namespace Authorization { + export interface Client { + type: 'kernel_managed'; + } + } + } + + /** + * 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. + */ + export interface AgentCardWalletVaultItemSpec { + provider: 'agentcard'; + + user_id?: string; + } +} + +export type WalletVaultItemState = + | WalletVaultItemState.LinkWalletState + | WalletVaultItemState.AgentCardWalletState; + +export namespace WalletVaultItemState { + export interface LinkWalletState { + provider: 'link'; + + status: 'pending_authorization' | 'connected' | 'declined' | 'reconnect_required' | 'degraded'; + + status_reason?: string; + } + + export interface AgentCardWalletState { + provider: 'agentcard'; + + status: 'pending_authorization' | 'connected' | 'degraded'; + + status_reason?: string; + + /** + * AgentCard user id linked to this wallet. Present once connected. + */ + user_id?: string; + } +} + +export type ItemListResponse = Array; + +export type ItemEventsResponse = Array; + +export interface ItemRetrieveParams { + /** + * Path param + */ + id_or_name: string; + + /** + * Query param: Live fields advertised by `available_expansions` to include in + * `expanded`. + */ + expand?: Array<'payment_methods'>; + + /** + * Query param: Hold for up to this many seconds while the item is pending + * authorization or approval. + */ + wait?: number; +} + +export interface ItemUpdateParams { + /** + * Path param + */ + 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. + */ + spec: CardVaultItemSpec; +} + +export interface ItemDeleteParams { + id_or_name: string; +} + +export interface ItemEventsParams { + /** + * Path param + */ + id_or_name: string; + + /** + * Query param: Return events after this event ID. + */ + after?: string; + + /** + * Query param: Long-poll for new events for up to this many seconds. + */ + wait?: number; +} + +export interface ItemPerformOperationParams { + /** + * Path param + */ + id_or_name: string; + + /** + * Body param + */ + type: 'authorize'; +} + +export type ItemUpsertParams = + | ItemUpsertParams.WalletVaultItemRequest + | ItemUpsertParams.CardVaultItemRequest; + +export declare namespace ItemUpsertParams { + export interface WalletVaultItemRequest { + /** + * Path param + */ + 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. + */ + spec: WalletVaultItemSpec; + + /** + * Body param + */ + type: 'wallet'; + } + + export interface CardVaultItemRequest { + /** + * Path param + */ + 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. + */ + spec: CardVaultItemSpec; + + /** + * Body param + */ + type: 'card'; + } +} + +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, + }; +} diff --git a/src/resources/vaults/vaults.ts b/src/resources/vaults/vaults.ts new file mode 100644 index 00000000..3031f0b3 --- /dev/null +++ b/src/resources/vaults/vaults.ts @@ -0,0 +1,125 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import { APIResource } from '../../core/resource'; +import * as ItemsAPI from './items'; +import { + AgentcardCheckoutAuthorization, + CardVaultItemSpec, + CardVaultItemState, + ItemDeleteParams, + ItemEventsParams, + ItemEventsResponse, + ItemListResponse, + ItemPerformOperationParams, + ItemRetrieveParams, + ItemUpdateParams, + ItemUpsertParams, + Items, + VaultCardAliases, + VaultItem, + VaultItemAction, + VaultItemEvent, + VaultPaymentMethod, + WalletVaultItemSpec, + WalletVaultItemState, +} from './items'; +import { APIPromise } from '../../core/api-promise'; +import { OffsetPagination, type OffsetPaginationParams, PagePromise } from '../../core/pagination'; +import { buildHeaders } from '../../internal/headers'; +import { RequestOptions } from '../../internal/request-options'; +import { path } from '../../internal/utils/path'; + +export class Vaults extends APIResource { + items: ItemsAPI.Items = new ItemsAPI.Items(this._client); + + /** + * Get a vault + */ + retrieve(idOrName: string, options?: RequestOptions): APIPromise { + return this._client.get(path`/vaults/${idOrName}`, options); + } + + /** + * List vaults in the current project + */ + list( + query: VaultListParams | null | undefined = {}, + options?: RequestOptions, + ): PagePromise { + return this._client.getAPIList('/vaults', OffsetPagination, { query, ...options }); + } + + /** + * Delete a vault and invalidate its items + */ + delete(idOrName: string, options?: RequestOptions): APIPromise { + return this._client.delete(path`/vaults/${idOrName}`, { + ...options, + headers: buildHeaders([{ Accept: '*/*' }, options?.headers]), + }); + } + + /** + * Create or retrieve a vault by immutable name + */ + upsert(body: VaultUpsertParams, options?: RequestOptions): APIPromise { + return this._client.post('/vaults', { body, ...options }); + } +} + +export type VaultsOffsetPagination = OffsetPagination; + +export interface Vault { + id: string; + + created_at: string; + + /** + * Immutable name assigned when the vault is created. + */ + name: string; + + updated_at: string; +} + +export interface VaultListParams extends OffsetPaginationParams {} + +export interface VaultUpsertParams { + /** + * Immutable name used to create or retrieve the vault. + */ + name: string; +} + +Vaults.Items = Items; + +export declare namespace Vaults { + export { + type Vault as Vault, + type VaultsOffsetPagination as VaultsOffsetPagination, + type VaultListParams as VaultListParams, + type VaultUpsertParams as VaultUpsertParams, + }; + + export { + Items as Items, + 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, + }; +} diff --git a/src/version.ts b/src/version.ts index f94f8b86..7b4f2ce4 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '0.98.0'; // x-release-please-version +export const VERSION = '0.99.0'; // x-release-please-version diff --git a/tests/api-resources/browsers/browsers.test.ts b/tests/api-resources/browsers/browsers.test.ts index 4c60d15e..e78d621f 100644 --- a/tests/api-resources/browsers/browsers.test.ts +++ b/tests/api-resources/browsers/browsers.test.ts @@ -75,6 +75,7 @@ describe('resource browsers', () => { }, }, timeout_seconds: 10, + vaults: [{ id: 'id', name: 'x' }], viewport: { height: 800, width: 1280, diff --git a/tests/api-resources/vaults/items.test.ts b/tests/api-resources/vaults/items.test.ts new file mode 100644 index 00000000..b5ee0ded --- /dev/null +++ b/tests/api-resources/vaults/items.test.ts @@ -0,0 +1,214 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import Kernel from '@onkernel/sdk'; + +const client = new Kernel({ + apiKey: 'My API Key', + baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010', +}); + +describe('resource items', () => { + // Mock server tests are disabled + test.skip('retrieve: only required params', async () => { + const responsePromise = client.vaults.items.retrieve('x', { id_or_name: 'id_or_name' }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('retrieve: required and optional params', async () => { + const response = await client.vaults.items.retrieve('x', { + id_or_name: 'id_or_name', + expand: ['payment_methods'], + wait: 0, + }); + }); + + // Mock server tests are disabled + test.skip('update: only required params', async () => { + const responsePromise = client.vaults.items.update('x', { + id_or_name: 'id_or_name', + spec: { + amount: 1, + context: + 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', + currency: 'bFx', + merchant_name: 'x', + merchant_url: 'https://example.com', + payment_method_id: 'x', + provider: 'link', + test: true, + wallet: 'wallet', + }, + }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('update: required and optional params', async () => { + const response = await client.vaults.items.update('x', { + id_or_name: 'id_or_name', + spec: { + amount: 1, + context: + 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', + currency: 'bFx', + merchant_name: 'x', + merchant_url: 'https://example.com', + payment_method_id: 'x', + provider: 'link', + test: true, + wallet: 'wallet', + expires_at: 0, + line_items: [ + { + name: 'name', + description: 'description', + image_url: 'image_url', + product_url: 'product_url', + quantity: 1, + sku: 'sku', + totals: [ + { + amount: 0, + display_text: 'display_text', + type: 'type', + }, + ], + unit_amount: 0, + url: 'url', + }, + ], + metadata: { foo: 'string' }, + totals: [ + { + amount: 0, + display_text: 'display_text', + type: 'type', + }, + ], + }, + }); + }); + + // Mock server tests are disabled + test.skip('list', async () => { + const responsePromise = client.vaults.items.list('id_or_name'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('delete: only required params', async () => { + const responsePromise = client.vaults.items.delete('x', { id_or_name: 'id_or_name' }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('delete: required and optional params', async () => { + const response = await client.vaults.items.delete('x', { id_or_name: 'id_or_name' }); + }); + + // Mock server tests are disabled + test.skip('events: only required params', async () => { + const responsePromise = client.vaults.items.events('key', { id_or_name: 'id_or_name' }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('events: required and optional params', async () => { + const response = await client.vaults.items.events('key', { + id_or_name: 'id_or_name', + after: 'after', + wait: 0, + }); + }); + + // Mock server tests are disabled + test.skip('performOperation: only required params', async () => { + const responsePromise = client.vaults.items.performOperation('key', { + id_or_name: 'id_or_name', + type: 'authorize', + }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('performOperation: required and optional params', async () => { + const response = await client.vaults.items.performOperation('key', { + id_or_name: 'id_or_name', + type: 'authorize', + }); + }); + + // Mock server tests are disabled + test.skip('upsert: only required params', async () => { + const responsePromise = client.vaults.items.upsert('x', { + id_or_name: 'id_or_name', + spec: { + authorization: { + client: { type: 'kernel_managed' }, + method: 'oauth', + }, + provider: 'link', + }, + type: 'wallet', + }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('upsert: required and optional params', async () => { + const response = await client.vaults.items.upsert('x', { + id_or_name: 'id_or_name', + spec: { + authorization: { + client: { type: 'kernel_managed' }, + method: 'oauth', + }, + provider: 'link', + }, + type: 'wallet', + }); + }); +}); diff --git a/tests/api-resources/vaults/vaults.test.ts b/tests/api-resources/vaults/vaults.test.ts new file mode 100644 index 00000000..b8348efe --- /dev/null +++ b/tests/api-resources/vaults/vaults.test.ts @@ -0,0 +1,71 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import Kernel from '@onkernel/sdk'; + +const client = new Kernel({ + apiKey: 'My API Key', + baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010', +}); + +describe('resource vaults', () => { + // Mock server tests are disabled + test.skip('retrieve', async () => { + const responsePromise = client.vaults.retrieve('id_or_name'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('list', async () => { + const responsePromise = client.vaults.list(); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + 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' }), + ).rejects.toThrow(Kernel.NotFoundError); + }); + + // Mock server tests are disabled + test.skip('delete', async () => { + const responsePromise = client.vaults.delete('id_or_name'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('upsert: only required params', async () => { + const responsePromise = client.vaults.upsert({ name: 'name' }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('upsert: required and optional params', async () => { + const response = await client.vaults.upsert({ name: 'name' }); + }); +});