-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathbrowser.go
More file actions
762 lines (712 loc) · 31 KB
/
browser.go
File metadata and controls
762 lines (712 loc) · 31 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
package kernel
import (
"bytes"
"context"
"encoding/json"
"errors"
"fmt"
"io"
"mime/multipart"
"net/http"
"net/url"
"slices"
"time"
"github.com/kernel/kernel-go-sdk/internal/apiform"
"github.com/kernel/kernel-go-sdk/internal/apijson"
"github.com/kernel/kernel-go-sdk/internal/apiquery"
"github.com/kernel/kernel-go-sdk/internal/requestconfig"
"github.com/kernel/kernel-go-sdk/option"
"github.com/kernel/kernel-go-sdk/packages/pagination"
"github.com/kernel/kernel-go-sdk/packages/param"
"github.com/kernel/kernel-go-sdk/packages/respjson"
"github.com/kernel/kernel-go-sdk/shared"
)
// Create and manage browser sessions.
//
// BrowserService contains methods and other services that help with interacting
// with the kernel API.
//
// Note, unlike clients, this service does not read variables from the environment
// automatically. You should not instantiate this service directly, and instead use
// the [NewBrowserService] method instead.
type BrowserService struct {
Options []option.RequestOption
// Record and manage browser session video replays.
Replays BrowserReplayService
// Read, write, and manage files on the browser instance.
Fs BrowserFService
// Execute and manage processes on the browser instance.
Process BrowserProcessService
// Stream logs from the browser instance.
Logs BrowserLogService
Computer BrowserComputerService
// Execute Playwright code against the browser instance.
Playwright BrowserPlaywrightService
}
// NewBrowserService generates a new service that applies the given options to each
// request. These options are applied after the parent client's options (if there
// is one), and before any request-specific options.
func NewBrowserService(opts ...option.RequestOption) (r BrowserService) {
r = BrowserService{}
r.Options = opts
r.Replays = NewBrowserReplayService(opts...)
r.Fs = NewBrowserFService(opts...)
r.Process = NewBrowserProcessService(opts...)
r.Logs = NewBrowserLogService(opts...)
r.Computer = NewBrowserComputerService(opts...)
r.Playwright = NewBrowserPlaywrightService(opts...)
return
}
// Create a new browser session from within an action.
func (r *BrowserService) New(ctx context.Context, body BrowserNewParams, opts ...option.RequestOption) (res *BrowserNewResponse, err error) {
opts = slices.Concat(r.Options, opts)
path := "browsers"
err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
return
}
// Get information about a browser session.
func (r *BrowserService) Get(ctx context.Context, id string, query BrowserGetParams, opts ...option.RequestOption) (res *BrowserGetResponse, err error) {
opts = slices.Concat(r.Options, opts)
if id == "" {
err = errors.New("missing required id parameter")
return
}
path := fmt.Sprintf("browsers/%s", id)
err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, query, &res, opts...)
return
}
// Update a browser session.
func (r *BrowserService) Update(ctx context.Context, id string, body BrowserUpdateParams, opts ...option.RequestOption) (res *BrowserUpdateResponse, err error) {
opts = slices.Concat(r.Options, opts)
if id == "" {
err = errors.New("missing required id parameter")
return
}
path := fmt.Sprintf("browsers/%s", id)
err = requestconfig.ExecuteNewRequest(ctx, http.MethodPatch, path, body, &res, opts...)
return
}
// List all browser sessions with pagination support. Use status parameter to
// filter by session state.
func (r *BrowserService) List(ctx context.Context, query BrowserListParams, opts ...option.RequestOption) (res *pagination.OffsetPagination[BrowserListResponse], err error) {
var raw *http.Response
opts = slices.Concat(r.Options, opts)
opts = append([]option.RequestOption{option.WithResponseInto(&raw)}, opts...)
path := "browsers"
cfg, err := requestconfig.NewRequestConfig(ctx, http.MethodGet, path, query, &res, opts...)
if err != nil {
return nil, err
}
err = cfg.Execute()
if err != nil {
return nil, err
}
res.SetPageConfig(cfg, raw)
return res, nil
}
// List all browser sessions with pagination support. Use status parameter to
// filter by session state.
func (r *BrowserService) ListAutoPaging(ctx context.Context, query BrowserListParams, opts ...option.RequestOption) *pagination.OffsetPaginationAutoPager[BrowserListResponse] {
return pagination.NewOffsetPaginationAutoPager(r.List(ctx, query, opts...))
}
// DEPRECATED: Use DELETE /browsers/{id} instead. Delete a persistent browser
// session by its persistent_id.
//
// Deprecated: deprecated
func (r *BrowserService) Delete(ctx context.Context, body BrowserDeleteParams, opts ...option.RequestOption) (err error) {
opts = slices.Concat(r.Options, opts)
opts = append([]option.RequestOption{option.WithHeader("Accept", "*/*")}, opts...)
path := "browsers"
err = requestconfig.ExecuteNewRequest(ctx, http.MethodDelete, path, body, nil, opts...)
return
}
// Delete a browser session by ID
func (r *BrowserService) DeleteByID(ctx context.Context, id string, opts ...option.RequestOption) (err error) {
opts = slices.Concat(r.Options, opts)
opts = append([]option.RequestOption{option.WithHeader("Accept", "*/*")}, opts...)
if id == "" {
err = errors.New("missing required id parameter")
return
}
path := fmt.Sprintf("browsers/%s", id)
err = requestconfig.ExecuteNewRequest(ctx, http.MethodDelete, path, nil, nil, opts...)
return
}
// Loads one or more unpacked extensions and restarts Chromium on the browser
// instance.
func (r *BrowserService) LoadExtensions(ctx context.Context, id string, body BrowserLoadExtensionsParams, opts ...option.RequestOption) (err error) {
opts = slices.Concat(r.Options, opts)
opts = append([]option.RequestOption{option.WithHeader("Accept", "*/*")}, opts...)
if id == "" {
err = errors.New("missing required id parameter")
return
}
path := fmt.Sprintf("browsers/%s/extensions", id)
err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, nil, opts...)
return
}
// DEPRECATED: Use timeout_seconds (up to 72 hours) and Profiles instead.
//
// Deprecated: deprecated
type BrowserPersistence struct {
// DEPRECATED: Unique identifier for the persistent browser session.
ID string `json:"id" api:"required"`
// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
JSON struct {
ID respjson.Field
ExtraFields map[string]respjson.Field
raw string
} `json:"-"`
}
// Returns the unmodified JSON received from the API
func (r BrowserPersistence) RawJSON() string { return r.JSON.raw }
func (r *BrowserPersistence) UnmarshalJSON(data []byte) error {
return apijson.UnmarshalRoot(data, r)
}
// ToParam converts this BrowserPersistence to a BrowserPersistenceParam.
//
// Warning: the fields of the param type will not be present. ToParam should only
// be used at the last possible moment before sending a request. Test for this with
// BrowserPersistenceParam.Overrides()
func (r BrowserPersistence) ToParam() BrowserPersistenceParam {
return param.Override[BrowserPersistenceParam](json.RawMessage(r.RawJSON()))
}
// DEPRECATED: Use timeout_seconds (up to 72 hours) and Profiles instead.
//
// Deprecated: deprecated
//
// The property ID is required.
type BrowserPersistenceParam struct {
// DEPRECATED: Unique identifier for the persistent browser session.
ID string `json:"id" api:"required"`
paramObj
}
func (r BrowserPersistenceParam) MarshalJSON() (data []byte, err error) {
type shadow BrowserPersistenceParam
return param.MarshalObject(r, (*shadow)(&r))
}
func (r *BrowserPersistenceParam) UnmarshalJSON(data []byte) error {
return apijson.UnmarshalRoot(data, r)
}
// Browser pool this session was acquired from, if any.
type BrowserPoolRef struct {
// Browser pool ID
ID string `json:"id" api:"required"`
// Browser pool name, if set
Name string `json:"name"`
// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
JSON struct {
ID respjson.Field
Name respjson.Field
ExtraFields map[string]respjson.Field
raw string
} `json:"-"`
}
// Returns the unmodified JSON received from the API
func (r BrowserPoolRef) RawJSON() string { return r.JSON.raw }
func (r *BrowserPoolRef) UnmarshalJSON(data []byte) error {
return apijson.UnmarshalRoot(data, r)
}
// Session usage metrics.
type BrowserUsage struct {
// Time in milliseconds the session was actively running.
UptimeMs int64 `json:"uptime_ms" api:"required"`
// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
JSON struct {
UptimeMs respjson.Field
ExtraFields map[string]respjson.Field
raw string
} `json:"-"`
}
// Returns the unmodified JSON received from the API
func (r BrowserUsage) RawJSON() string { return r.JSON.raw }
func (r *BrowserUsage) UnmarshalJSON(data []byte) error {
return apijson.UnmarshalRoot(data, r)
}
// Browser profile metadata.
type Profile struct {
// Unique identifier for the profile
ID string `json:"id" api:"required"`
// Timestamp when the profile was created
CreatedAt time.Time `json:"created_at" api:"required" format:"date-time"`
// Timestamp when the profile was last used
LastUsedAt time.Time `json:"last_used_at" format:"date-time"`
// Optional, easier-to-reference name for the profile
Name string `json:"name" api:"nullable"`
// Timestamp when the profile was last updated
UpdatedAt time.Time `json:"updated_at" format:"date-time"`
// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
JSON struct {
ID respjson.Field
CreatedAt respjson.Field
LastUsedAt respjson.Field
Name respjson.Field
UpdatedAt respjson.Field
ExtraFields map[string]respjson.Field
raw string
} `json:"-"`
}
// Returns the unmodified JSON received from the API
func (r Profile) RawJSON() string { return r.JSON.raw }
func (r *Profile) UnmarshalJSON(data []byte) error {
return apijson.UnmarshalRoot(data, r)
}
type BrowserNewResponse struct {
// Websocket URL for Chrome DevTools Protocol connections to the browser session
CdpWsURL string `json:"cdp_ws_url" api:"required"`
// When the browser session was created.
CreatedAt time.Time `json:"created_at" api:"required" format:"date-time"`
// Whether the browser session is running in headless mode.
Headless bool `json:"headless" api:"required"`
// Unique identifier for the browser session
SessionID string `json:"session_id" api:"required"`
// Whether the browser session is running in stealth mode.
Stealth bool `json:"stealth" api:"required"`
// The number of seconds of inactivity before the browser session is terminated.
TimeoutSeconds int64 `json:"timeout_seconds" api:"required"`
// Remote URL for live viewing the browser session. Only available for non-headless
// browsers.
BrowserLiveViewURL string `json:"browser_live_view_url"`
// When the browser session was soft-deleted. Only present for deleted sessions.
DeletedAt time.Time `json:"deleted_at" format:"date-time"`
// Whether the browser session has hardware-accelerated GPU rendering.
GPU bool `json:"gpu"`
// Whether the browser session is running in kiosk mode.
KioskMode bool `json:"kiosk_mode"`
// DEPRECATED: Use timeout_seconds (up to 72 hours) and Profiles instead.
//
// Deprecated: deprecated
Persistence BrowserPersistence `json:"persistence"`
// Browser pool this session was acquired from, if any.
Pool BrowserPoolRef `json:"pool"`
// Browser profile metadata.
Profile Profile `json:"profile"`
// ID of the proxy associated with this browser session, if any.
ProxyID string `json:"proxy_id"`
// Session usage metrics.
Usage BrowserUsage `json:"usage"`
// Initial browser window size in pixels with optional refresh rate. If omitted,
// image defaults apply (1920x1080@25). Arbitrary viewport dimensions are accepted,
// but the following configurations are known-good and fully tested: 2560x1440@10,
// 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60.
// Viewports outside this list may exhibit unstable live view or recording
// behavior. If refresh_rate is not provided, it will be automatically determined
// based on the resolution (higher resolutions use lower refresh rates to keep
// bandwidth reasonable).
Viewport shared.BrowserViewport `json:"viewport"`
// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
JSON struct {
CdpWsURL respjson.Field
CreatedAt respjson.Field
Headless respjson.Field
SessionID respjson.Field
Stealth respjson.Field
TimeoutSeconds respjson.Field
BrowserLiveViewURL respjson.Field
DeletedAt respjson.Field
GPU respjson.Field
KioskMode respjson.Field
Persistence respjson.Field
Pool respjson.Field
Profile respjson.Field
ProxyID respjson.Field
Usage respjson.Field
Viewport respjson.Field
ExtraFields map[string]respjson.Field
raw string
} `json:"-"`
}
// Returns the unmodified JSON received from the API
func (r BrowserNewResponse) RawJSON() string { return r.JSON.raw }
func (r *BrowserNewResponse) UnmarshalJSON(data []byte) error {
return apijson.UnmarshalRoot(data, r)
}
type BrowserGetResponse struct {
// Websocket URL for Chrome DevTools Protocol connections to the browser session
CdpWsURL string `json:"cdp_ws_url" api:"required"`
// When the browser session was created.
CreatedAt time.Time `json:"created_at" api:"required" format:"date-time"`
// Whether the browser session is running in headless mode.
Headless bool `json:"headless" api:"required"`
// Unique identifier for the browser session
SessionID string `json:"session_id" api:"required"`
// Whether the browser session is running in stealth mode.
Stealth bool `json:"stealth" api:"required"`
// The number of seconds of inactivity before the browser session is terminated.
TimeoutSeconds int64 `json:"timeout_seconds" api:"required"`
// Remote URL for live viewing the browser session. Only available for non-headless
// browsers.
BrowserLiveViewURL string `json:"browser_live_view_url"`
// When the browser session was soft-deleted. Only present for deleted sessions.
DeletedAt time.Time `json:"deleted_at" format:"date-time"`
// Whether the browser session has hardware-accelerated GPU rendering.
GPU bool `json:"gpu"`
// Whether the browser session is running in kiosk mode.
KioskMode bool `json:"kiosk_mode"`
// DEPRECATED: Use timeout_seconds (up to 72 hours) and Profiles instead.
//
// Deprecated: deprecated
Persistence BrowserPersistence `json:"persistence"`
// Browser pool this session was acquired from, if any.
Pool BrowserPoolRef `json:"pool"`
// Browser profile metadata.
Profile Profile `json:"profile"`
// ID of the proxy associated with this browser session, if any.
ProxyID string `json:"proxy_id"`
// Session usage metrics.
Usage BrowserUsage `json:"usage"`
// Initial browser window size in pixels with optional refresh rate. If omitted,
// image defaults apply (1920x1080@25). Arbitrary viewport dimensions are accepted,
// but the following configurations are known-good and fully tested: 2560x1440@10,
// 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60.
// Viewports outside this list may exhibit unstable live view or recording
// behavior. If refresh_rate is not provided, it will be automatically determined
// based on the resolution (higher resolutions use lower refresh rates to keep
// bandwidth reasonable).
Viewport shared.BrowserViewport `json:"viewport"`
// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
JSON struct {
CdpWsURL respjson.Field
CreatedAt respjson.Field
Headless respjson.Field
SessionID respjson.Field
Stealth respjson.Field
TimeoutSeconds respjson.Field
BrowserLiveViewURL respjson.Field
DeletedAt respjson.Field
GPU respjson.Field
KioskMode respjson.Field
Persistence respjson.Field
Pool respjson.Field
Profile respjson.Field
ProxyID respjson.Field
Usage respjson.Field
Viewport respjson.Field
ExtraFields map[string]respjson.Field
raw string
} `json:"-"`
}
// Returns the unmodified JSON received from the API
func (r BrowserGetResponse) RawJSON() string { return r.JSON.raw }
func (r *BrowserGetResponse) UnmarshalJSON(data []byte) error {
return apijson.UnmarshalRoot(data, r)
}
type BrowserUpdateResponse struct {
// Websocket URL for Chrome DevTools Protocol connections to the browser session
CdpWsURL string `json:"cdp_ws_url" api:"required"`
// When the browser session was created.
CreatedAt time.Time `json:"created_at" api:"required" format:"date-time"`
// Whether the browser session is running in headless mode.
Headless bool `json:"headless" api:"required"`
// Unique identifier for the browser session
SessionID string `json:"session_id" api:"required"`
// Whether the browser session is running in stealth mode.
Stealth bool `json:"stealth" api:"required"`
// The number of seconds of inactivity before the browser session is terminated.
TimeoutSeconds int64 `json:"timeout_seconds" api:"required"`
// Remote URL for live viewing the browser session. Only available for non-headless
// browsers.
BrowserLiveViewURL string `json:"browser_live_view_url"`
// When the browser session was soft-deleted. Only present for deleted sessions.
DeletedAt time.Time `json:"deleted_at" format:"date-time"`
// Whether the browser session has hardware-accelerated GPU rendering.
GPU bool `json:"gpu"`
// Whether the browser session is running in kiosk mode.
KioskMode bool `json:"kiosk_mode"`
// DEPRECATED: Use timeout_seconds (up to 72 hours) and Profiles instead.
//
// Deprecated: deprecated
Persistence BrowserPersistence `json:"persistence"`
// Browser pool this session was acquired from, if any.
Pool BrowserPoolRef `json:"pool"`
// Browser profile metadata.
Profile Profile `json:"profile"`
// ID of the proxy associated with this browser session, if any.
ProxyID string `json:"proxy_id"`
// Session usage metrics.
Usage BrowserUsage `json:"usage"`
// Initial browser window size in pixels with optional refresh rate. If omitted,
// image defaults apply (1920x1080@25). Arbitrary viewport dimensions are accepted,
// but the following configurations are known-good and fully tested: 2560x1440@10,
// 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60.
// Viewports outside this list may exhibit unstable live view or recording
// behavior. If refresh_rate is not provided, it will be automatically determined
// based on the resolution (higher resolutions use lower refresh rates to keep
// bandwidth reasonable).
Viewport shared.BrowserViewport `json:"viewport"`
// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
JSON struct {
CdpWsURL respjson.Field
CreatedAt respjson.Field
Headless respjson.Field
SessionID respjson.Field
Stealth respjson.Field
TimeoutSeconds respjson.Field
BrowserLiveViewURL respjson.Field
DeletedAt respjson.Field
GPU respjson.Field
KioskMode respjson.Field
Persistence respjson.Field
Pool respjson.Field
Profile respjson.Field
ProxyID respjson.Field
Usage respjson.Field
Viewport respjson.Field
ExtraFields map[string]respjson.Field
raw string
} `json:"-"`
}
// Returns the unmodified JSON received from the API
func (r BrowserUpdateResponse) RawJSON() string { return r.JSON.raw }
func (r *BrowserUpdateResponse) UnmarshalJSON(data []byte) error {
return apijson.UnmarshalRoot(data, r)
}
type BrowserListResponse struct {
// Websocket URL for Chrome DevTools Protocol connections to the browser session
CdpWsURL string `json:"cdp_ws_url" api:"required"`
// When the browser session was created.
CreatedAt time.Time `json:"created_at" api:"required" format:"date-time"`
// Whether the browser session is running in headless mode.
Headless bool `json:"headless" api:"required"`
// Unique identifier for the browser session
SessionID string `json:"session_id" api:"required"`
// Whether the browser session is running in stealth mode.
Stealth bool `json:"stealth" api:"required"`
// The number of seconds of inactivity before the browser session is terminated.
TimeoutSeconds int64 `json:"timeout_seconds" api:"required"`
// Remote URL for live viewing the browser session. Only available for non-headless
// browsers.
BrowserLiveViewURL string `json:"browser_live_view_url"`
// When the browser session was soft-deleted. Only present for deleted sessions.
DeletedAt time.Time `json:"deleted_at" format:"date-time"`
// Whether the browser session has hardware-accelerated GPU rendering.
GPU bool `json:"gpu"`
// Whether the browser session is running in kiosk mode.
KioskMode bool `json:"kiosk_mode"`
// DEPRECATED: Use timeout_seconds (up to 72 hours) and Profiles instead.
//
// Deprecated: deprecated
Persistence BrowserPersistence `json:"persistence"`
// Browser pool this session was acquired from, if any.
Pool BrowserPoolRef `json:"pool"`
// Browser profile metadata.
Profile Profile `json:"profile"`
// ID of the proxy associated with this browser session, if any.
ProxyID string `json:"proxy_id"`
// Session usage metrics.
Usage BrowserUsage `json:"usage"`
// Initial browser window size in pixels with optional refresh rate. If omitted,
// image defaults apply (1920x1080@25). Arbitrary viewport dimensions are accepted,
// but the following configurations are known-good and fully tested: 2560x1440@10,
// 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60.
// Viewports outside this list may exhibit unstable live view or recording
// behavior. If refresh_rate is not provided, it will be automatically determined
// based on the resolution (higher resolutions use lower refresh rates to keep
// bandwidth reasonable).
Viewport shared.BrowserViewport `json:"viewport"`
// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
JSON struct {
CdpWsURL respjson.Field
CreatedAt respjson.Field
Headless respjson.Field
SessionID respjson.Field
Stealth respjson.Field
TimeoutSeconds respjson.Field
BrowserLiveViewURL respjson.Field
DeletedAt respjson.Field
GPU respjson.Field
KioskMode respjson.Field
Persistence respjson.Field
Pool respjson.Field
Profile respjson.Field
ProxyID respjson.Field
Usage respjson.Field
Viewport respjson.Field
ExtraFields map[string]respjson.Field
raw string
} `json:"-"`
}
// Returns the unmodified JSON received from the API
func (r BrowserListResponse) RawJSON() string { return r.JSON.raw }
func (r *BrowserListResponse) UnmarshalJSON(data []byte) error {
return apijson.UnmarshalRoot(data, r)
}
type BrowserNewParams struct {
// If true, launches a hardware-accelerated browser with GPU rendering. Requires
// Start-Up or Enterprise plan.
GPU param.Opt[bool] `json:"gpu,omitzero"`
// If true, launches the browser using a headless image (no VNC/GUI). Defaults to
// false.
Headless param.Opt[bool] `json:"headless,omitzero"`
// action invocation ID
InvocationID param.Opt[string] `json:"invocation_id,omitzero"`
// If true, launches the browser in kiosk mode to hide address bar and tabs in live
// view.
KioskMode param.Opt[bool] `json:"kiosk_mode,omitzero"`
// Optional proxy to associate to the browser session. Must reference a proxy
// belonging to the caller's org.
ProxyID param.Opt[string] `json:"proxy_id,omitzero"`
// If true, launches the browser in stealth mode to reduce detection by anti-bot
// mechanisms.
Stealth param.Opt[bool] `json:"stealth,omitzero"`
// The number of seconds of inactivity before the browser session is terminated.
// Activity includes CDP connections and live view connections. Defaults to 60
// seconds. Minimum allowed is 10 seconds. Maximum allowed is 259200 (72 hours). We
// check for inactivity every 5 seconds, so the actual timeout behavior you will
// see is +/- 5 seconds around the specified value.
TimeoutSeconds param.Opt[int64] `json:"timeout_seconds,omitzero"`
// List of browser extensions to load into the session. Provide each by id or name.
Extensions []shared.BrowserExtensionParam `json:"extensions,omitzero"`
// DEPRECATED: Use timeout_seconds (up to 72 hours) and Profiles instead.
Persistence BrowserPersistenceParam `json:"persistence,omitzero"`
// Profile selection for the browser session. Provide either id or name. If
// specified, the matching profile will be loaded into the browser session.
// Profiles must be created beforehand.
Profile shared.BrowserProfileParam `json:"profile,omitzero"`
// Initial browser window size in pixels with optional refresh rate. If omitted,
// image defaults apply (1920x1080@25). Arbitrary viewport dimensions are accepted,
// but the following configurations are known-good and fully tested: 2560x1440@10,
// 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60.
// Viewports outside this list may exhibit unstable live view or recording
// behavior. If refresh_rate is not provided, it will be automatically determined
// based on the resolution (higher resolutions use lower refresh rates to keep
// bandwidth reasonable).
Viewport shared.BrowserViewportParam `json:"viewport,omitzero"`
paramObj
}
func (r BrowserNewParams) MarshalJSON() (data []byte, err error) {
type shadow BrowserNewParams
return param.MarshalObject(r, (*shadow)(&r))
}
func (r *BrowserNewParams) UnmarshalJSON(data []byte) error {
return apijson.UnmarshalRoot(data, r)
}
type BrowserGetParams struct {
// When true, includes soft-deleted browser sessions in the lookup.
IncludeDeleted param.Opt[bool] `query:"include_deleted,omitzero" json:"-"`
paramObj
}
// URLQuery serializes [BrowserGetParams]'s query parameters as `url.Values`.
func (r BrowserGetParams) URLQuery() (v url.Values, err error) {
return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
ArrayFormat: apiquery.ArrayQueryFormatComma,
NestedFormat: apiquery.NestedQueryFormatBrackets,
})
}
type BrowserUpdateParams struct {
// ID of the proxy to use. Omit to leave unchanged, set to empty string to remove
// proxy.
ProxyID param.Opt[string] `json:"proxy_id,omitzero"`
// Profile to load into the browser session. Only allowed if the session does not
// already have a profile loaded.
Profile shared.BrowserProfileParam `json:"profile,omitzero"`
// Viewport configuration to apply to the browser session.
Viewport BrowserUpdateParamsViewport `json:"viewport,omitzero"`
paramObj
}
func (r BrowserUpdateParams) MarshalJSON() (data []byte, err error) {
type shadow BrowserUpdateParams
return param.MarshalObject(r, (*shadow)(&r))
}
func (r *BrowserUpdateParams) UnmarshalJSON(data []byte) error {
return apijson.UnmarshalRoot(data, r)
}
// Viewport configuration to apply to the browser session.
type BrowserUpdateParamsViewport struct {
// If true, allow the viewport change even when a live view or recording/replay is
// active. Active recordings will be gracefully stopped and restarted at the new
// resolution as separate segments. If false (default), the resize is refused when
// a live view or recording is active.
Force param.Opt[bool] `json:"force,omitzero"`
shared.BrowserViewportParam
}
func (r BrowserUpdateParamsViewport) MarshalJSON() (data []byte, err error) {
type shadow struct {
*BrowserUpdateParamsViewport
MarshalJSON bool `json:"-"` // Prevent inheriting [json.Marshaler] from the embedded field
}
return param.MarshalObject(r, shadow{&r, false})
}
type BrowserListParams struct {
// Deprecated: Use status=all instead. When true, includes soft-deleted browser
// sessions in the results alongside active sessions.
IncludeDeleted param.Opt[bool] `query:"include_deleted,omitzero" json:"-"`
// Maximum number of results to return. Defaults to 20, maximum 100.
Limit param.Opt[int64] `query:"limit,omitzero" json:"-"`
// Number of results to skip. Defaults to 0.
Offset param.Opt[int64] `query:"offset,omitzero" json:"-"`
// Search browsers by session ID, profile ID, or proxy ID.
Query param.Opt[string] `query:"query,omitzero" json:"-"`
// Filter sessions by status. "active" returns only active sessions (default),
// "deleted" returns only soft-deleted sessions, "all" returns both.
//
// Any of "active", "deleted", "all".
Status BrowserListParamsStatus `query:"status,omitzero" json:"-"`
paramObj
}
// URLQuery serializes [BrowserListParams]'s query parameters as `url.Values`.
func (r BrowserListParams) URLQuery() (v url.Values, err error) {
return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
ArrayFormat: apiquery.ArrayQueryFormatComma,
NestedFormat: apiquery.NestedQueryFormatBrackets,
})
}
// Filter sessions by status. "active" returns only active sessions (default),
// "deleted" returns only soft-deleted sessions, "all" returns both.
type BrowserListParamsStatus string
const (
BrowserListParamsStatusActive BrowserListParamsStatus = "active"
BrowserListParamsStatusDeleted BrowserListParamsStatus = "deleted"
BrowserListParamsStatusAll BrowserListParamsStatus = "all"
)
type BrowserDeleteParams struct {
// Persistent browser identifier
PersistentID string `query:"persistent_id" api:"required" json:"-"`
paramObj
}
// URLQuery serializes [BrowserDeleteParams]'s query parameters as `url.Values`.
func (r BrowserDeleteParams) URLQuery() (v url.Values, err error) {
return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
ArrayFormat: apiquery.ArrayQueryFormatComma,
NestedFormat: apiquery.NestedQueryFormatBrackets,
})
}
type BrowserLoadExtensionsParams struct {
// List of extensions to upload and activate
Extensions []BrowserLoadExtensionsParamsExtension `json:"extensions,omitzero" api:"required"`
paramObj
}
func (r BrowserLoadExtensionsParams) MarshalMultipart() (data []byte, contentType string, err error) {
buf := bytes.NewBuffer(nil)
writer := multipart.NewWriter(buf)
err = apiform.MarshalRoot(r, writer)
if err == nil {
err = apiform.WriteExtras(writer, r.ExtraFields())
}
if err != nil {
writer.Close()
return nil, "", err
}
err = writer.Close()
if err != nil {
return nil, "", err
}
return buf.Bytes(), writer.FormDataContentType(), nil
}
// The properties Name, ZipFile are required.
type BrowserLoadExtensionsParamsExtension struct {
// Folder name to place the extension under /home/kernel/extensions/<name>
Name string `json:"name" api:"required"`
// Zip archive containing an unpacked Chromium extension (must include
// manifest.json)
ZipFile io.Reader `json:"zip_file,omitzero" api:"required" format:"binary"`
paramObj
}
func (r BrowserLoadExtensionsParamsExtension) MarshalJSON() (data []byte, err error) {
type shadow BrowserLoadExtensionsParamsExtension
return param.MarshalObject(r, (*shadow)(&r))
}
func (r *BrowserLoadExtensionsParamsExtension) UnmarshalJSON(data []byte) error {
return apijson.UnmarshalRoot(data, r)
}