@onkernel/sdk 0.121.0 → 0.123.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/client.d.mts +4 -4
  3. package/client.d.mts.map +1 -1
  4. package/client.d.ts +4 -4
  5. package/client.d.ts.map +1 -1
  6. package/client.js.map +1 -1
  7. package/client.mjs.map +1 -1
  8. package/package.json +1 -1
  9. package/resources/browser-pools.d.mts +21 -7
  10. package/resources/browser-pools.d.mts.map +1 -1
  11. package/resources/browser-pools.d.ts +21 -7
  12. package/resources/browser-pools.d.ts.map +1 -1
  13. package/resources/browsers/browsers.d.mts +62 -28
  14. package/resources/browsers/browsers.d.mts.map +1 -1
  15. package/resources/browsers/browsers.d.ts +62 -28
  16. package/resources/browsers/browsers.d.ts.map +1 -1
  17. package/resources/browsers/browsers.js.map +1 -1
  18. package/resources/browsers/browsers.mjs.map +1 -1
  19. package/resources/browsers/index.d.mts +1 -1
  20. package/resources/browsers/index.d.mts.map +1 -1
  21. package/resources/browsers/index.d.ts +1 -1
  22. package/resources/browsers/index.d.ts.map +1 -1
  23. package/resources/browsers/index.js.map +1 -1
  24. package/resources/browsers/index.mjs.map +1 -1
  25. package/resources/browsers/telemetry.d.mts +94 -33
  26. package/resources/browsers/telemetry.d.mts.map +1 -1
  27. package/resources/browsers/telemetry.d.ts +94 -33
  28. package/resources/browsers/telemetry.d.ts.map +1 -1
  29. package/resources/browsers/telemetry.js +4 -1
  30. package/resources/browsers/telemetry.js.map +1 -1
  31. package/resources/browsers/telemetry.mjs +4 -1
  32. package/resources/browsers/telemetry.mjs.map +1 -1
  33. package/resources/config-registry/config-registry.d.mts +2 -2
  34. package/resources/config-registry/config-registry.d.ts +2 -2
  35. package/resources/index.d.mts +2 -2
  36. package/resources/index.d.mts.map +1 -1
  37. package/resources/index.d.ts +2 -2
  38. package/resources/index.d.ts.map +1 -1
  39. package/resources/index.js.map +1 -1
  40. package/resources/index.mjs.map +1 -1
  41. package/resources/invocations.d.mts +4 -0
  42. package/resources/invocations.d.mts.map +1 -1
  43. package/resources/invocations.d.ts +4 -0
  44. package/resources/invocations.d.ts.map +1 -1
  45. package/resources/proxies.d.mts +12 -12
  46. package/resources/proxies.d.ts +12 -12
  47. package/resources/vaults/index.d.mts +1 -1
  48. package/resources/vaults/index.d.mts.map +1 -1
  49. package/resources/vaults/index.d.ts +1 -1
  50. package/resources/vaults/index.d.ts.map +1 -1
  51. package/resources/vaults/index.js.map +1 -1
  52. package/resources/vaults/index.mjs.map +1 -1
  53. package/resources/vaults/items.d.mts +61 -19
  54. package/resources/vaults/items.d.mts.map +1 -1
  55. package/resources/vaults/items.d.ts +61 -19
  56. package/resources/vaults/items.d.ts.map +1 -1
  57. package/resources/vaults/items.js +2 -2
  58. package/resources/vaults/items.mjs +2 -2
  59. package/resources/vaults/vaults.d.mts +62 -1
  60. package/resources/vaults/vaults.d.mts.map +1 -1
  61. package/resources/vaults/vaults.d.ts +62 -1
  62. package/resources/vaults/vaults.d.ts.map +1 -1
  63. package/resources/vaults/vaults.js +19 -0
  64. package/resources/vaults/vaults.js.map +1 -1
  65. package/resources/vaults/vaults.mjs +19 -0
  66. package/resources/vaults/vaults.mjs.map +1 -1
  67. package/src/client.ts +4 -0
  68. package/src/resources/browser-pools.ts +22 -7
  69. package/src/resources/browsers/browsers.ts +68 -27
  70. package/src/resources/browsers/index.ts +1 -0
  71. package/src/resources/browsers/telemetry.ts +126 -33
  72. package/src/resources/config-registry/config-registry.ts +2 -2
  73. package/src/resources/index.ts +2 -0
  74. package/src/resources/invocations.ts +5 -0
  75. package/src/resources/proxies.ts +12 -12
  76. package/src/resources/vaults/index.ts +1 -0
  77. package/src/resources/vaults/items.ts +63 -19
  78. package/src/resources/vaults/vaults.ts +73 -0
  79. package/src/version.ts +1 -1
  80. package/version.d.mts +1 -1
  81. package/version.d.ts +1 -1
  82. package/version.js +1 -1
  83. package/version.mjs +1 -1
@@ -47,7 +47,10 @@ export class Telemetry extends APIResource {
47
47
  * stream closes when the browser session terminates. Each event frame includes an
48
48
  * id: field containing a monotonically increasing sequence number; pass it as
49
49
  * Last-Event-ID on reconnect to resume without gaps. The event: field is never
50
- * set; all frames carry JSON in the data: field. A keepalive comment frame is sent
50
+ * set; event frames carry JSON in the data: field. A frame with an id: field and
51
+ * no data: field moves Last-Event-ID past events that were not delivered, because
52
+ * a type filter excluded them or they could not be decoded or exceeded the size
53
+ * limit; SSE clients dispatch no event for it. A keepalive comment frame is sent
51
54
  * every 15 seconds when no events arrive. Returns 404 if the browser session does
52
55
  * not exist. If telemetry was not enabled on the session, the stream opens but no
53
56
  * events are delivered. Fresh connections only see new events; pass replay=all to
@@ -194,15 +197,19 @@ export namespace BrowserCallStack {
194
197
  }
195
198
 
196
199
  /**
197
- * A visible captcha challenge reached a terminal outcome.
200
+ * A captcha challenge reached an observed or inferred terminal outcome.
198
201
  */
199
202
  export interface BrowserCaptchaChallengeResultEvent {
200
203
  category: 'captcha';
201
204
 
202
205
  /**
203
- * Per-challenge payload. This event is emitted once per challenge and determines
204
- * its overall outcome; captcha_solve_started and captcha_solve_result describe
205
- * individual tasks and may occur multiple times within the challenge.
206
+ * An observed challenge emits one outcome across any number of solver tasks. For
207
+ * eligible providers without a widget observer, each successful token task emits
208
+ * an inferred solved result instead; multiple such results may belong to one
209
+ * challenge. Failed tasks and image_challenge rounds produce no inferred result.
210
+ * Exactly one of challenge_id or task_id is present: challenge_id on an observed
211
+ * result, task_id on an inferred one. A challenge whose tasks all fail produces
212
+ * task events only, so consumers fall back to captcha_solve_result for it.
206
213
  */
207
214
  data: BrowserCaptchaChallengeResultEvent.Data;
208
215
 
@@ -226,15 +233,17 @@ export interface BrowserCaptchaChallengeResultEvent {
226
233
 
227
234
  export namespace BrowserCaptchaChallengeResultEvent {
228
235
  /**
229
- * Per-challenge payload. This event is emitted once per challenge and determines
230
- * its overall outcome; captcha_solve_started and captcha_solve_result describe
231
- * individual tasks and may occur multiple times within the challenge.
236
+ * An observed challenge emits one outcome across any number of solver tasks. For
237
+ * eligible providers without a widget observer, each successful token task emits
238
+ * an inferred solved result instead; multiple such results may belong to one
239
+ * challenge. Failed tasks and image_challenge rounds produce no inferred result.
240
+ * Exactly one of challenge_id or task_id is present: challenge_id on an observed
241
+ * result, task_id on an inferred one. A challenge whose tasks all fail produces
242
+ * task events only, so consumers fall back to captcha_solve_result for it.
232
243
  */
233
244
  export interface Data {
234
245
  /**
235
- * Captcha kind. Enterprise reCAPTCHA variants are grouped into their version
236
- * bucket (recaptcha_v2 or recaptcha_v3), press-and-hold challenges use
237
- * press_and_hold, and unlisted kinds use other.
246
+ * @deprecated Deprecated: use captcha_provider.
238
247
  */
239
248
  captcha_type:
240
249
  | 'hcaptcha'
@@ -245,34 +254,67 @@ export namespace BrowserCaptchaChallengeResultEvent {
245
254
  | 'press_and_hold'
246
255
  | 'other';
247
256
 
257
+ /**
258
+ * Wall-clock duration from the challenge appearing to its terminal outcome,
259
+ * covering every solver attempt in between. For an inferred result, the duration
260
+ * of its solver task.
261
+ */
262
+ duration_ms: number;
263
+
264
+ /**
265
+ * Terminal outcome of a challenge. solved: the page observed the challenge clear
266
+ * after a solver attempt, or an inferred result reports a token for the whole
267
+ * widget without page observation. failure: a terminal solver failure occurred, or
268
+ * all attempts ended while the challenge remained. timeout: the challenge-level
269
+ * wait budget expired while the challenge remained. abandoned: observation ended
270
+ * without an attributable terminal challenge outcome. This includes a dismissed
271
+ * widget or page unload without a solved signal or terminal solver outcome, and a
272
+ * token appearing while multiple same-provider challenges are open, because the
273
+ * producer cannot attribute that token to this visible challenge. A
274
+ * captcha_solve_result with the same challenge_id may therefore report success
275
+ * while the challenge result reports abandoned. A solved challenge does not prove
276
+ * the site accepted the token or that the guarded action succeeded.
277
+ */
278
+ status: 'solved' | 'failure' | 'timeout' | 'abandoned';
279
+
280
+ /**
281
+ * Captcha product the challenge belongs to, not the service that solved it.
282
+ * Enterprise reCAPTCHA variants are grouped into their version bucket
283
+ * (recaptcha_v2 or recaptcha_v3), FunCaptcha uses arkose, press-and-hold
284
+ * challenges served by HUMAN (formerly PerimeterX) use human, and unlisted
285
+ * products use other.
286
+ */
287
+ captcha_provider?:
288
+ | 'hcaptcha'
289
+ | 'recaptcha_v2'
290
+ | 'recaptcha_v3'
291
+ | 'turnstile'
292
+ | 'geetest'
293
+ | 'arkose'
294
+ | 'human'
295
+ | 'other';
296
+
248
297
  /**
249
298
  * Opaque identifier shared by events for one visible challenge. An image-grid
250
299
  * captcha may create multiple task_id values for one challenge_id. The same value
251
300
  * may continue across a page reload when the challenge episode continues. It does
252
301
  * not indicate task ordering or challenge completion.
253
302
  */
254
- challenge_id: string;
303
+ challenge_id?: string;
255
304
 
256
305
  /**
257
- * Wall-clock duration from the challenge appearing to its terminal outcome,
258
- * covering every solver attempt in between.
306
+ * True when the relay derived this result from a successful token task without
307
+ * observing the page. An inferred result has task_id instead of challenge_id.
308
+ * Absent on page-observed results.
259
309
  */
260
- duration_ms: number;
310
+ inferred?: boolean;
261
311
 
262
312
  /**
263
- * Terminal outcome of the visible challenge. solved: the page observed the
264
- * challenge clear after a solver attempt. failure: a terminal solver failure
265
- * occurred, or all attempts ended while the challenge remained. timeout: the
266
- * challenge-level wait budget expired while the challenge remained. abandoned:
267
- * observation ended without an attributable terminal challenge outcome. This
268
- * includes a dismissed widget or page unload without a solved signal or terminal
269
- * solver outcome, and a token appearing while multiple same-provider challenges
270
- * are open, because the producer cannot attribute that token to this visible
271
- * challenge. A captcha_solve_result with the same challenge_id may therefore
272
- * report success while the challenge result reports abandoned. A solved challenge
273
- * does not prove the site accepted the token or that the guarded action succeeded.
313
+ * The task_id of the solver task an inferred result was derived from. Join on it
314
+ * to pair the result with that task's captcha_solve_started and
315
+ * captcha_solve_result. Present only when inferred is true.
274
316
  */
275
- status: 'solved' | 'failure' | 'timeout' | 'abandoned';
317
+ task_id?: string;
276
318
 
277
319
  /**
278
320
  * Host of the page where the challenge appeared.
@@ -315,9 +357,7 @@ export interface BrowserCaptchaSolveResultEvent {
315
357
  export namespace BrowserCaptchaSolveResultEvent {
316
358
  export interface Data {
317
359
  /**
318
- * Captcha kind. Enterprise reCAPTCHA variants are grouped into their version
319
- * bucket (recaptcha_v2 or recaptcha_v3), press-and-hold challenges use
320
- * press_and_hold, and unlisted kinds use other.
360
+ * @deprecated Deprecated: use captcha_provider and task_kind.
321
361
  */
322
362
  captcha_type:
323
363
  | 'hcaptcha'
@@ -343,6 +383,23 @@ export namespace BrowserCaptchaSolveResultEvent {
343
383
  */
344
384
  status: 'success' | 'failure' | 'timeout' | 'abandoned';
345
385
 
386
+ /**
387
+ * Captcha product the challenge belongs to, not the service that solved it.
388
+ * Enterprise reCAPTCHA variants are grouped into their version bucket
389
+ * (recaptcha_v2 or recaptcha_v3), FunCaptcha uses arkose, press-and-hold
390
+ * challenges served by HUMAN (formerly PerimeterX) use human, and unlisted
391
+ * products use other.
392
+ */
393
+ captcha_provider?:
394
+ | 'hcaptcha'
395
+ | 'recaptcha_v2'
396
+ | 'recaptcha_v3'
397
+ | 'turnstile'
398
+ | 'geetest'
399
+ | 'arkose'
400
+ | 'human'
401
+ | 'other';
402
+
346
403
  /**
347
404
  * Opaque identifier shared by events for one visible challenge. An image-grid
348
405
  * captcha may create multiple task_id values for one challenge_id. The same value
@@ -362,6 +419,11 @@ export namespace BrowserCaptchaSolveResultEvent {
362
419
  */
363
420
  task_id?: string;
364
421
 
422
+ /**
423
+ * What the solver task produces. Absent when the producer cannot tell.
424
+ */
425
+ task_kind?: 'token' | 'image_challenge' | 'press_and_hold';
426
+
365
427
  /**
366
428
  * Host of the page where the captcha was solved.
367
429
  */
@@ -415,9 +477,7 @@ export namespace BrowserCaptchaSolveStartedEvent {
415
477
  */
416
478
  export interface Data {
417
479
  /**
418
- * Captcha kind. Enterprise reCAPTCHA variants are grouped into their version
419
- * bucket (recaptcha_v2 or recaptcha_v3), press-and-hold challenges use
420
- * press_and_hold, and unlisted kinds use other.
480
+ * @deprecated Deprecated: use captcha_provider and task_kind.
421
481
  */
422
482
  captcha_type:
423
483
  | 'hcaptcha'
@@ -428,6 +488,23 @@ export namespace BrowserCaptchaSolveStartedEvent {
428
488
  | 'press_and_hold'
429
489
  | 'other';
430
490
 
491
+ /**
492
+ * Captcha product the challenge belongs to, not the service that solved it.
493
+ * Enterprise reCAPTCHA variants are grouped into their version bucket
494
+ * (recaptcha_v2 or recaptcha_v3), FunCaptcha uses arkose, press-and-hold
495
+ * challenges served by HUMAN (formerly PerimeterX) use human, and unlisted
496
+ * products use other.
497
+ */
498
+ captcha_provider?:
499
+ | 'hcaptcha'
500
+ | 'recaptcha_v2'
501
+ | 'recaptcha_v3'
502
+ | 'turnstile'
503
+ | 'geetest'
504
+ | 'arkose'
505
+ | 'human'
506
+ | 'other';
507
+
431
508
  /**
432
509
  * Opaque identifier shared by events for one visible challenge. An image-grid
433
510
  * captcha may create multiple task_id values for one challenge_id. The same value
@@ -441,6 +518,11 @@ export namespace BrowserCaptchaSolveStartedEvent {
441
518
  */
442
519
  task_id?: string;
443
520
 
521
+ /**
522
+ * What the solver task produces. Absent when the producer cannot tell.
523
+ */
524
+ task_kind?: 'token' | 'image_challenge' | 'press_and_hold';
525
+
444
526
  /**
445
527
  * Host of the page where the captcha is being solved. May be empty for solver
446
528
  * tasks that carry no page URL.
@@ -4917,6 +4999,17 @@ export interface TelemetryStreamParams {
4917
4999
  */
4918
5000
  replay?: string;
4919
5001
 
5002
+ /**
5003
+ * Query param: Deliver only these event types, such as captcha_solve_started or
5004
+ * captcha_challenge_result. Repeat the parameter or pass comma-separated values
5005
+ * for multiple types. Keepalive frames are always delivered. Filtered-out events
5006
+ * are not sent. An id-only frame carrying the latest skipped id is sent about
5007
+ * every 15 seconds while skipped events keep arriving, and otherwise with the next
5008
+ * keepalive or when the stream ends, so the connection stays active and
5009
+ * Last-Event-ID moves past them; a reconnect resumes after the skipped events.
5010
+ */
5011
+ type?: Array<string>;
5012
+
4920
5013
  /**
4921
5014
  * Header param: Last event sequence number for SSE reconnection (sent by SSE
4922
5015
  * clients on reconnect). Takes precedence over replay when both are present, so
@@ -336,8 +336,8 @@ export namespace Proxy {
336
336
  */
337
337
  export interface IspProxyConfig {
338
338
  /**
339
- * ISO 3166 country code. Supported countries are US, GB, FR, DE, and SG. Defaults
340
- * to US if not provided.
339
+ * ISO 3166 country code. Supported countries are US, GB, FR, DE, SG, and KR.
340
+ * Defaults to US if not provided.
341
341
  */
342
342
  country?: string;
343
343
  }
@@ -54,6 +54,7 @@ export {
54
54
  type BrowserReplResult,
55
55
  type BrowserReplTextContent,
56
56
  type BrowserUsage,
57
+ type BrowserVideoMemory,
57
58
  type Profile,
58
59
  type Tags,
59
60
  type VaultReference,
@@ -210,6 +211,7 @@ export {
210
211
  export {
211
212
  Vaults,
212
213
  type Vault,
214
+ type VaultEncryptionKey,
213
215
  type VaultListParams,
214
216
  type VaultUpsertParams,
215
217
  type VaultsOffsetPagination,
@@ -601,6 +601,11 @@ export namespace InvocationListBrowsersResponse {
601
601
  */
602
602
  vaults?: Array<BrowsersAPI.VaultReference>;
603
603
 
604
+ /**
605
+ * Video memory (VRAM) of the GPU browser session. Only present when gpu is true.
606
+ */
607
+ video_memory?: BrowsersAPI.BrowserVideoMemory;
608
+
604
609
  /**
605
610
  * Initial browser window size in pixels with optional refresh rate. If omitted,
606
611
  * image defaults apply (1920x1080@25). For GPU images, the default is
@@ -166,8 +166,8 @@ export namespace ProxyCreateResponse {
166
166
  */
167
167
  export interface IspProxyConfig {
168
168
  /**
169
- * ISO 3166 country code. Supported countries are US, GB, FR, DE, and SG. Defaults
170
- * to US if not provided.
169
+ * ISO 3166 country code. Supported countries are US, GB, FR, DE, SG, and KR.
170
+ * Defaults to US if not provided.
171
171
  */
172
172
  country?: string;
173
173
  }
@@ -315,8 +315,8 @@ export namespace ProxyRetrieveResponse {
315
315
  */
316
316
  export interface IspProxyConfig {
317
317
  /**
318
- * ISO 3166 country code. Supported countries are US, GB, FR, DE, and SG. Defaults
319
- * to US if not provided.
318
+ * ISO 3166 country code. Supported countries are US, GB, FR, DE, SG, and KR.
319
+ * Defaults to US if not provided.
320
320
  */
321
321
  country?: string;
322
322
  }
@@ -464,8 +464,8 @@ export namespace ProxyUpdateResponse {
464
464
  */
465
465
  export interface IspProxyConfig {
466
466
  /**
467
- * ISO 3166 country code. Supported countries are US, GB, FR, DE, and SG. Defaults
468
- * to US if not provided.
467
+ * ISO 3166 country code. Supported countries are US, GB, FR, DE, SG, and KR.
468
+ * Defaults to US if not provided.
469
469
  */
470
470
  country?: string;
471
471
  }
@@ -613,8 +613,8 @@ export namespace ProxyListResponse {
613
613
  */
614
614
  export interface IspProxyConfig {
615
615
  /**
616
- * ISO 3166 country code. Supported countries are US, GB, FR, DE, and SG. Defaults
617
- * to US if not provided.
616
+ * ISO 3166 country code. Supported countries are US, GB, FR, DE, SG, and KR.
617
+ * Defaults to US if not provided.
618
618
  */
619
619
  country?: string;
620
620
  }
@@ -762,8 +762,8 @@ export namespace ProxyCheckResponse {
762
762
  */
763
763
  export interface IspProxyConfig {
764
764
  /**
765
- * ISO 3166 country code. Supported countries are US, GB, FR, DE, and SG. Defaults
766
- * to US if not provided.
765
+ * ISO 3166 country code. Supported countries are US, GB, FR, DE, SG, and KR.
766
+ * Defaults to US if not provided.
767
767
  */
768
768
  country?: string;
769
769
  }
@@ -891,8 +891,8 @@ export namespace ProxyCreateParams {
891
891
  */
892
892
  export interface IspProxyConfig {
893
893
  /**
894
- * ISO 3166 country code. Supported countries are US, GB, FR, DE, and SG. Defaults
895
- * to US if not provided.
894
+ * ISO 3166 country code. Supported countries are US, GB, FR, DE, SG, and KR.
895
+ * Defaults to US if not provided.
896
896
  */
897
897
  country?: string;
898
898
  }
@@ -75,6 +75,7 @@ export {
75
75
  export {
76
76
  Vaults,
77
77
  type Vault,
78
+ type VaultEncryptionKey,
78
79
  type VaultListParams,
79
80
  type VaultUpsertParams,
80
81
  type VaultsOffsetPagination,
@@ -146,8 +146,8 @@ export class Items extends APIResource {
146
146
  * return 400 (invalid request or targets), 403 (access or destination denied), 404
147
147
  * (resource not found), or 409 (item or browser not ready). Once writing starts,
148
148
  * known partial failures and indeterminate field outcomes return 200 with status
149
- * `failed` or `unknown`, not an automatic-retry signal. A transport error may
150
- * leave the outcome unknown; do not automatically retry.
149
+ * `failed` or `unknown`. Fill never submits the page, so it is safe to retry after
150
+ * a failure, an `unknown` outcome, or a transport error.
151
151
  *
152
152
  * @example
153
153
  * ```ts
@@ -769,6 +769,22 @@ export interface CredentialVaultFieldInput {
769
769
  */
770
770
  type: CredentialVaultFieldType;
771
771
 
772
+ /**
773
+ * Alternative to value for custom credential collection web apps. Use this only if
774
+ * you run your own credential collection web app and want values encrypted in the
775
+ * browser, sent to your backend still encrypted, and forwarded to Kernel's API
776
+ * still encrypted. In every other case, including server-side code that already
777
+ * holds the plaintext, use value. The field's value encrypted client-side as a
778
+ * compact JWE with alg ECDH-ES and enc A256GCM to the key from GET
779
+ * /vaults/{id_or_name}/encryption_key, with that key's kid in the protected
780
+ * header. Compression is not supported. The decrypted value follows the same rules
781
+ * as value, including that an empty string clears the field on update. A kid that
782
+ * is not this vault's key returns 400 encryption_key_mismatch; fetch the key again
783
+ * and re-encrypt. Other malformed or undecryptable values return 400
784
+ * invalid_request. The whole request body is limited to 128 KiB.
785
+ */
786
+ encrypted_value?: string;
787
+
772
788
  /**
773
789
  * Optional human-readable display label. It is returned as non-secret metadata and
774
790
  * never affects value keys, updates, or browser fills. Use single-line, trimmed
@@ -791,7 +807,9 @@ export interface CredentialVaultFieldInput {
791
807
  /**
792
808
  * Optional initial value satisfying the declared type, at most 16 KiB in UTF-8
793
809
  * bytes. Omit to leave unset; null and empty strings are rejected on creation.
794
- * Sensitive values are encrypted and never copied into the returned spec.
810
+ * Sensitive values are encrypted and never copied into the returned spec. Use this
811
+ * unless your own credential collection web app encrypts values in the browser;
812
+ * mutually exclusive with encrypted_value.
795
813
  */
796
814
  value?: string;
797
815
  }
@@ -819,7 +837,28 @@ export interface CredentialVaultFieldState {
819
837
  */
820
838
  export type CredentialVaultFieldType = 'text' | 'email' | 'password' | 'totp';
821
839
 
840
+ /**
841
+ * Set exactly one of value or encrypted_value. Use value unless the update comes
842
+ * from your own credential collection web app that encrypts values in the browser;
843
+ * see encrypted_value.
844
+ */
822
845
  export interface CredentialVaultFieldUpdate {
846
+ /**
847
+ * Alternative to value for custom credential collection web apps. Use this only if
848
+ * you run your own credential collection web app and want values encrypted in the
849
+ * browser, sent to your backend still encrypted, and forwarded to Kernel's API
850
+ * still encrypted. In every other case, including server-side code that already
851
+ * holds the plaintext, use value. The field's value encrypted client-side as a
852
+ * compact JWE with alg ECDH-ES and enc A256GCM to the key from GET
853
+ * /vaults/{id_or_name}/encryption_key, with that key's kid in the protected
854
+ * header. Compression is not supported. The decrypted value follows the same rules
855
+ * as value, including that an empty string clears the field on update. A kid that
856
+ * is not this vault's key returns 400 encryption_key_mismatch; fetch the key again
857
+ * and re-encrypt. Other malformed or undecryptable values return 400
858
+ * invalid_request. The whole request body is limited to 128 KiB.
859
+ */
860
+ encrypted_value?: string;
861
+
823
862
  /**
824
863
  * Replacement value (at most 16 KiB in UTF-8 bytes), or null or an empty string to
825
864
  * immediately clear the stored value. Clearing a required form-supported field
@@ -828,7 +867,7 @@ export interface CredentialVaultFieldUpdate {
828
867
  * seed, never a current code. Clearing a required totp field returns 400 because
829
868
  * it cannot be collected in a form.
830
869
  */
831
- value: string | null;
870
+ value?: string | null;
832
871
  }
833
872
 
834
873
  export interface CredentialVaultItem {
@@ -954,14 +993,15 @@ export namespace CredentialVaultItem {
954
993
  * they choose 1Password, connect their account and request access to a login in
955
994
  * their own non-shared vault; passkeys are not supported. If they decline or that
956
995
  * path fails, collect a Kernel-hosted credential item instead. Never automatically
957
- * retry an uncertain 1Password request or fill. Do not use credential items for
958
- * credit card data. Use wallet and card item types instead. Kernel credentials
959
- * declare fields and may enter pending_collection. 1Password credentials either
960
- * reference a connected credential_account or store a supplied access token and
961
- * integration key encrypted on the item. They store no login values or selectors.
962
- * Managed auth credentials reference a managed auth connection in the same project
963
- * that already has a saved credential, and read it at fill time; they store no
964
- * values. Repeating the original creation request returns the current item without
996
+ * retry an uncertain 1Password request. After an uncertain fill, inspect the page
997
+ * to see the result of the fill. Do not use credential items for credit card data.
998
+ * Use wallet and card item types instead. Kernel credentials declare fields and
999
+ * may enter pending_collection. 1Password credentials either reference a connected
1000
+ * credential_account or store a supplied access token and integration key
1001
+ * encrypted on the item. They store no login values or selectors. Managed auth
1002
+ * credentials reference a managed auth connection in the same project that already
1003
+ * has a saved credential, and read it at fill time; they store no values.
1004
+ * Repeating the original creation request returns the current item without
965
1005
  * overwriting later state. A different request at the same key returns 409.
966
1006
  */
967
1007
  export interface CredentialVaultItemRequest {
@@ -1067,8 +1107,10 @@ export interface CredentialVaultItemUpdateRequest {
1067
1107
  * atomic: previously filled fields are not rolled back. Never submit the form or
1068
1108
  * click buttons, though input/change events may trigger site behavior. Link and
1069
1109
  * Kernel cards use fill for browser checkout and do not expose aliases or support
1070
- * egress substitution. Do not automatically retry a failed or indeterminate
1071
- * operation.
1110
+ * egress substitution. Fill does not consume the item, so a failed or
1111
+ * indeterminate fill is safe to retry; a retry rewrites the same fields. A retry
1112
+ * right after an indeterminate fill may wait up to 15 seconds for the earlier
1113
+ * attempt's browser lock to expire.
1072
1114
  *
1073
1115
  * Secret values are never returned or included in operation logs, traces, audit
1074
1116
  * events, or error details. This does not prevent an agent with unrestricted
@@ -1733,17 +1775,19 @@ export interface OnePasswordFillVaultItemOperationResult {
1733
1775
  /**
1734
1776
  * Kernel's outcome of the extension call. fill_submitted means the extension
1735
1777
  * reported submission, not website authentication. fill_failed means the extension
1736
- * returned a known failure and may include error_code. fill_unknown means
1737
- * submission may have happened without a conclusive response; it has no error_code
1738
- * and must not be retried in the same browser.
1778
+ * returned a known failure and includes error_code. fill_unknown means the form
1779
+ * may have been filled or submitted without a conclusive result; inspect the page
1780
+ * to see the result of the fill.
1739
1781
  */
1740
1782
  status: 'fill_submitted' | 'fill_failed' | 'fill_unknown';
1741
1783
 
1742
1784
  type: '1pw_fill';
1743
1785
 
1744
1786
  /**
1745
- * Present only for a conclusive fill_failed response. These are allowlisted
1746
- * 1Password extension codes, never raw errors, secrets, or page content.
1787
+ * Present for fill_failed, and for fill_unknown when the extension reported
1788
+ * autosubmitFailed (it filled and submitted the form but could not confirm the
1789
+ * fill finished). These are allowlisted 1Password extension codes, never raw
1790
+ * errors, secrets, or page content.
1747
1791
  */
1748
1792
  error_code?: 'fillFailed' | 'autosubmitFailed' | 'noExistingCredentials' | 'authenticationFailed';
1749
1793
  }
@@ -132,6 +132,26 @@ export class Vaults extends APIResource {
132
132
  });
133
133
  }
134
134
 
135
+ /**
136
+ * Returns the public key that custom credential collection web apps use to encrypt
137
+ * values in the browser. Use this only if you run your own credential collection
138
+ * web app and want values encrypted in the browser, sent to your backend still
139
+ * encrypted, and forwarded to Kernel's API still encrypted. In every other case,
140
+ * including server-side code that already holds the plaintext, use value. The page
141
+ * encrypts each value to this key, your backend forwards the ciphertext unchanged
142
+ * as encrypted_value when creating or updating a credential item in this vault,
143
+ * and Kernel decrypts it.
144
+ *
145
+ * @example
146
+ * ```ts
147
+ * const vaultEncryptionKey =
148
+ * await client.vaults.retrieveEncryptionKey('id_or_name');
149
+ * ```
150
+ */
151
+ retrieveEncryptionKey(idOrName: string, options?: RequestOptions): APIPromise<VaultEncryptionKey> {
152
+ return this._client.get(path`/vaults/${idOrName}/encryption_key`, options);
153
+ }
154
+
135
155
  /**
136
156
  * Free organizations can store up to 3 non-deleted vaults across all projects.
137
157
  * Paid plans and active trials have no vault cap. Retrieving an existing vault by
@@ -164,6 +184,58 @@ export interface Vault {
164
184
  updated_at: string;
165
185
  }
166
186
 
187
+ /**
188
+ * Public key for encrypted_value on credential fields. Use this only if you run
189
+ * your own credential collection web app and want values encrypted in the browser,
190
+ * sent to your backend still encrypted, and forwarded to Kernel's API still
191
+ * encrypted. In every other case, including server-side code that already holds
192
+ * the plaintext, use value. Each vault has its own key; a value encrypted for one
193
+ * vault is rejected by every other vault. The key is created on first request and
194
+ * stays the same for the vault's lifetime, so it may be cached.
195
+ */
196
+ export interface VaultEncryptionKey {
197
+ /**
198
+ * JWE key management algorithm.
199
+ */
200
+ alg: 'ECDH-ES';
201
+
202
+ /**
203
+ * JWE content encryption algorithm.
204
+ */
205
+ enc: 'A256GCM';
206
+
207
+ /**
208
+ * P-256 public key in JWK form.
209
+ */
210
+ jwk: VaultEncryptionKey.Jwk;
211
+
212
+ /**
213
+ * Key ID. Set it as the kid protected header of every encrypted_value.
214
+ */
215
+ kid: string;
216
+ }
217
+
218
+ export namespace VaultEncryptionKey {
219
+ /**
220
+ * P-256 public key in JWK form.
221
+ */
222
+ export interface Jwk {
223
+ crv: 'P-256';
224
+
225
+ kty: 'EC';
226
+
227
+ /**
228
+ * Base64url-encoded x coordinate.
229
+ */
230
+ x: string;
231
+
232
+ /**
233
+ * Base64url-encoded y coordinate.
234
+ */
235
+ y: string;
236
+ }
237
+ }
238
+
167
239
  export interface VaultListParams extends OffsetPaginationParams {
168
240
  /**
169
241
  * Case-insensitive substring match against vault name. IDs match by exact value.
@@ -183,6 +255,7 @@ Vaults.Items = Items;
183
255
  export declare namespace Vaults {
184
256
  export {
185
257
  type Vault as Vault,
258
+ type VaultEncryptionKey as VaultEncryptionKey,
186
259
  type VaultsOffsetPagination as VaultsOffsetPagination,
187
260
  type VaultListParams as VaultListParams,
188
261
  type VaultUpsertParams as VaultUpsertParams,
package/src/version.ts CHANGED
@@ -1 +1 @@
1
- export const VERSION = '0.121.0'; // x-release-please-version
1
+ export const VERSION = '0.123.0'; // x-release-please-version
package/version.d.mts CHANGED
@@ -1,2 +1,2 @@
1
- export declare const VERSION = "0.121.0";
1
+ export declare const VERSION = "0.123.0";
2
2
  //# sourceMappingURL=version.d.mts.map
package/version.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- export declare const VERSION = "0.121.0";
1
+ export declare const VERSION = "0.123.0";
2
2
  //# sourceMappingURL=version.d.ts.map
package/version.js CHANGED
@@ -1,5 +1,5 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.VERSION = void 0;
4
- exports.VERSION = '0.121.0'; // x-release-please-version
4
+ exports.VERSION = '0.123.0'; // x-release-please-version
5
5
  //# sourceMappingURL=version.js.map
package/version.mjs CHANGED
@@ -1,2 +1,2 @@
1
- export const VERSION = '0.121.0'; // x-release-please-version
1
+ export const VERSION = '0.123.0'; // x-release-please-version
2
2
  //# sourceMappingURL=version.mjs.map