agental-sdk 0.2.0 → 0.3.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.
- package/README.md +1 -0
- package/dist/client.d.ts +25 -2
- package/dist/client.js +28 -0
- package/dist/index.d.ts +1 -1
- package/dist/openapi.d.ts +565 -2
- package/dist/sandbox.d.ts +31 -3
- package/dist/sandbox.js +23 -1
- package/dist/template.d.ts +11 -1
- package/dist/template.js +14 -0
- package/dist/types.d.ts +10 -0
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -112,6 +112,7 @@ await sandbox.stop({ keepMemory: true }); // or keep its memory too, at 10%: sta
|
|
|
112
112
|
await sandbox.start(); // waits until it is running, also when it has to be brought back from storage
|
|
113
113
|
|
|
114
114
|
const copy = await sandbox.fork(); // a new sandbox with the same disk
|
|
115
|
+
const live = await sandbox.fork({ memory: true }); // or one that goes on from where it was, every process running on (Firecracker boxes only)
|
|
115
116
|
|
|
116
117
|
const snapshot = await sandbox.snapshot("before-upgrade");
|
|
117
118
|
await sandbox.restore(snapshot.id); // roll the disk back
|
package/dist/client.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { Http, type AgentalOptions } from "./http.js";
|
|
2
2
|
import { Email, Sandbox, type CreateOptions } from "./sandbox.js";
|
|
3
3
|
import { Templates } from "./template.js";
|
|
4
|
-
import type { AccountEmail, AccountExport, ApiKey, ApiKeyUsage, Billing, Burst, Catalog, HostRoute, Invite, Me, Member, Organization, Region, AutoReload, Checkout, DataRetention, CreateApiKey, CreatedApiKey, MetricsAtMoment, Policy, Prices, RunningOverTime, SandboxSummary, SandboxJob, SandboxJobItem, SandboxJobPreview, Size, Snapshot, Team, TeamRole, Telemetry, TelemetryTest, RunsOnRepository, RunsOnRepositories, Usage, Webhook } from "./types.js";
|
|
4
|
+
import type { AccountEmail, AccountExport, ApiKey, ApiKeyUsage, Billing, Burst, Catalog, HostRoute, Invite, Me, Member, Organization, Region, AutoReload, Checkout, DataRetention, CreateApiKey, CreatedApiKey, MetricsAtMoment, Policy, Prices, RunningOverTime, SandboxSummary, SandboxJob, SandboxJobItem, SandboxJobPreview, Size, Snapshot, Team, TeamRole, Telemetry, TelemetryTest, RunsOnRepository, RunsOnRepositories, Usage, Webhook, EgressAccount } from "./types.js";
|
|
5
5
|
/** What a list of sandboxes is narrowed to. Each field left out narrows nothing; a list of values is any of them. */
|
|
6
6
|
export interface SandboxFilter {
|
|
7
7
|
/** Tags every sandbox has. */
|
|
@@ -27,6 +27,10 @@ export interface SandboxFilter {
|
|
|
27
27
|
memoryKept?: boolean;
|
|
28
28
|
/** open, blocked or allowlist. */
|
|
29
29
|
outbound?: string | readonly string[];
|
|
30
|
+
/** What they are doing: low-cpu, disk-full, memory-full or not-read. Any of them. */
|
|
31
|
+
activity?: string | readonly string[];
|
|
32
|
+
/** None of these. */
|
|
33
|
+
notActivity?: string | readonly string[];
|
|
30
34
|
/** Each key at this value; "*" for any value, the key being set. */
|
|
31
35
|
metadata?: Record<string, string>;
|
|
32
36
|
/** No key at this value; "*" for the key not being set. */
|
|
@@ -35,7 +39,7 @@ export interface SandboxFilter {
|
|
|
35
39
|
text?: string;
|
|
36
40
|
}
|
|
37
41
|
/** How a page of sandboxes is sorted. Only created and -created keep a walk through the pages exact while sandboxes change. */
|
|
38
|
-
export type SandboxSort = "created" | "-created" | "name" | "-name" | "status" | "-status" | "stopped" | "-stopped" | "cost" | "-cost";
|
|
42
|
+
export type SandboxSort = "created" | "-created" | "name" | "-name" | "status" | "-status" | "stopped" | "-stopped" | "cost" | "-cost" | "-cpu" | "-memory" | "-disk";
|
|
39
43
|
/** A page of sandboxes, and what to pass as cursor for the next one: null when this is the last. */
|
|
40
44
|
export interface SandboxPage {
|
|
41
45
|
sandboxes: Sandbox[];
|
|
@@ -331,6 +335,25 @@ export declare class Agental {
|
|
|
331
335
|
* defaultBudgetMicros. It answers with the account's burst as it stands now.
|
|
332
336
|
*/
|
|
333
337
|
setBurstBudget(budgetMicros: number | null): Promise<Burst>;
|
|
338
|
+
/**
|
|
339
|
+
* Whether the account may send sandboxes out through residential addresses, and what it
|
|
340
|
+
* still needs: plan (Fleet or larger), card (one saved), use_case (setEgressUseCase()).
|
|
341
|
+
* With what a GB costs, what it has spent this month, its budget, and why its residential
|
|
342
|
+
* connections are refused now, if they are. Amounts are millionths of a US dollar.
|
|
343
|
+
*/
|
|
344
|
+
egress(): Promise<EgressAccount>;
|
|
345
|
+
/**
|
|
346
|
+
* Tells us what the account's sandboxes will use residential addresses for, in a few
|
|
347
|
+
* sentences (20 to 2,000 characters): said once for the whole account. Sent again, it
|
|
348
|
+
* replaces what was sent. An owner's key only. Only where policy() says residentialEgress.
|
|
349
|
+
*/
|
|
350
|
+
setEgressUseCase(useCase: string): Promise<EgressAccount>;
|
|
351
|
+
/**
|
|
352
|
+
* Sets the most the account's residential traffic costs in a month, in millionths of a US
|
|
353
|
+
* dollar: 0 refuses all of it. null gives it the default again, defaultBudgetMicros. An
|
|
354
|
+
* owner's key only. Only where policy() says residentialEgress.
|
|
355
|
+
*/
|
|
356
|
+
setEgressBudget(budgetMicros: number | null): Promise<EgressAccount>;
|
|
334
357
|
/**
|
|
335
358
|
* Running time and what it comes to at the list price, by sandbox, by key, by day and by hour, and the mail of the same
|
|
336
359
|
* window. With apiKeyId, one key or several, only the sandboxes those keys made, "console" standing for those made in
|
package/dist/client.js
CHANGED
|
@@ -18,6 +18,8 @@ function filterQuery(filter) {
|
|
|
18
18
|
many("templateId", filter.templateId);
|
|
19
19
|
many("createdBy", filter.createdBy);
|
|
20
20
|
many("outbound", filter.outbound);
|
|
21
|
+
many("activity", filter.activity);
|
|
22
|
+
many("notActivity", filter.notActivity);
|
|
21
23
|
many("createdAfter", time(filter.createdAfter));
|
|
22
24
|
many("createdBefore", time(filter.createdBefore));
|
|
23
25
|
many("stoppedBefore", time(filter.stoppedBefore));
|
|
@@ -124,6 +126,7 @@ class Sandboxes {
|
|
|
124
126
|
...(options.snapshotId !== undefined ? { snapshotId: options.snapshotId } : {}),
|
|
125
127
|
...(options.ttlSeconds !== undefined ? { ttlSeconds: options.ttlSeconds } : {}),
|
|
126
128
|
...(options.network ? { network: options.network } : {}),
|
|
129
|
+
...(options.egress ? { egress: options.egress } : {}),
|
|
127
130
|
...(options.sshKeys !== undefined ? { sshKeys: options.sshKeys } : {}),
|
|
128
131
|
...(options.tags !== undefined ? { tags: options.tags } : {}),
|
|
129
132
|
...(options.metadata !== undefined ? { metadata: options.metadata } : {}),
|
|
@@ -452,6 +455,31 @@ export class Agental {
|
|
|
452
455
|
async setBurstBudget(budgetMicros) {
|
|
453
456
|
return (await this.http.json({ method: "PUT", path: "/v1/burst/budget", body: { budgetMicros }, replay: true })).body;
|
|
454
457
|
}
|
|
458
|
+
/**
|
|
459
|
+
* Whether the account may send sandboxes out through residential addresses, and what it
|
|
460
|
+
* still needs: plan (Fleet or larger), card (one saved), use_case (setEgressUseCase()).
|
|
461
|
+
* With what a GB costs, what it has spent this month, its budget, and why its residential
|
|
462
|
+
* connections are refused now, if they are. Amounts are millionths of a US dollar.
|
|
463
|
+
*/
|
|
464
|
+
async egress() {
|
|
465
|
+
return (await this.http.json({ method: "GET", path: "/v1/egress", replay: true })).body;
|
|
466
|
+
}
|
|
467
|
+
/**
|
|
468
|
+
* Tells us what the account's sandboxes will use residential addresses for, in a few
|
|
469
|
+
* sentences (20 to 2,000 characters): said once for the whole account. Sent again, it
|
|
470
|
+
* replaces what was sent. An owner's key only. Only where policy() says residentialEgress.
|
|
471
|
+
*/
|
|
472
|
+
async setEgressUseCase(useCase) {
|
|
473
|
+
return (await this.http.json({ method: "PUT", path: "/v1/egress/use-case", body: { useCase }, replay: true })).body;
|
|
474
|
+
}
|
|
475
|
+
/**
|
|
476
|
+
* Sets the most the account's residential traffic costs in a month, in millionths of a US
|
|
477
|
+
* dollar: 0 refuses all of it. null gives it the default again, defaultBudgetMicros. An
|
|
478
|
+
* owner's key only. Only where policy() says residentialEgress.
|
|
479
|
+
*/
|
|
480
|
+
async setEgressBudget(budgetMicros) {
|
|
481
|
+
return (await this.http.json({ method: "PUT", path: "/v1/egress/budget", body: { budgetMicros }, replay: true })).body;
|
|
482
|
+
}
|
|
455
483
|
/**
|
|
456
484
|
* Running time and what it comes to at the list price, by sandbox, by key, by day and by hour, and the mail of the same
|
|
457
485
|
* window. With apiKeyId, one key or several, only the sandboxes those keys made, "console" standing for those made in
|
package/dist/index.d.ts
CHANGED
|
@@ -6,5 +6,5 @@ export { Browser, Commands, Desktop, Email, Files, Sandbox, Schedules, Ssh } fro
|
|
|
6
6
|
export { Secrets, Template, Templates } from "./template.js";
|
|
7
7
|
export type { TemplateChanges } from "./template.js";
|
|
8
8
|
export type { BurstOptions, CommandLine, CreateOptions, DesktopButton, ExecEvent, ExecOptions, SandboxChanges, ScreenshotOptions, SendEmailOptions, StartOptions, StopOptions, WaitOptions } from "./sandbox.js";
|
|
9
|
-
export type { AccountEmail, ApiKey, ApiKeyAction, ApiKeyPreset, ApiKeyUsage, Billing, BrowserState, Burst, BurstFee, BurstQuote, Catalog, Region, AutoReload, Checkout, Command, CreateSchedule, CreateApiKey, CreatedApiKey, DesktopLink, DesktopScreenshot, DesktopState, EmailMessage, EmailMessageList, EmailMessageSummary, ExecResult, HiddenVariable, HostRoute, Invite, Me, Member, Organization, MetricsAtMoment, MetricsReading, NetworkRule, Operation, PlainVariable, Plan, Policy, Prices, RunningOverTime, SandboxAutoStop, SandboxEmail, SandboxInfo, SandboxSummary, SandboxJob, SandboxJobItem, SandboxJobPreview, SandboxMetrics, SandboxNetwork, SandboxNetworkDetail, SandboxOwnNetwork, SandboxStatus, SandboxTemplate, SandboxUsage, Schedule, ScheduleRun, SecretVariable, SendEmail, SetAutoStop, Size, Snapshot, SshKey, SshState, UpdateSchedule, Team, TeamRole, Telemetry, DataRetention, AccountExport, TelemetryTest, RunsOnRepository, RunsOnRepositories, TemplateApplied, TemplateInfo, TemplateNetwork, TemplateSandbox, TemplateStart, TemplateSsh, Usage, Webhook, WebhookDelivery, } from "./types.js";
|
|
9
|
+
export type { AccountEmail, ApiKey, ApiKeyAction, ApiKeyPreset, ApiKeyUsage, Billing, BrowserState, Burst, BurstFee, BurstQuote, Catalog, Region, AutoReload, Checkout, Command, CreateSchedule, CreateApiKey, CreatedApiKey, DesktopLink, DesktopScreenshot, DesktopState, Egress, EgressAccount, EgressInput, EmailMessage, EmailMessageList, EmailMessageSummary, ExecResult, HiddenVariable, HostRoute, Invite, Me, Member, Organization, MetricsAtMoment, MetricsReading, NetworkRule, Operation, PlainVariable, Plan, Policy, Prices, RunningOverTime, SandboxAutoStop, SandboxEmail, SandboxInfo, SandboxSummary, SandboxJob, SandboxJobItem, SandboxJobPreview, SandboxMetrics, SandboxNetwork, SandboxNetworkDetail, SandboxOwnNetwork, SandboxStatus, SandboxTemplate, SandboxUsage, Schedule, ScheduleRun, SecretVariable, SendEmail, SetAutoStop, Size, Snapshot, SshKey, SshState, UpdateSchedule, Team, TeamRole, Telemetry, DataRetention, AccountExport, TelemetryTest, RunsOnRepository, RunsOnRepositories, TemplateApplied, TemplateInfo, TemplateNetwork, TemplateSandbox, TemplateStart, TemplateSsh, Usage, Webhook, WebhookDelivery, } from "./types.js";
|
|
10
10
|
export { verifyWebhook } from "./webhooks.js";
|
package/dist/openapi.d.ts
CHANGED
|
@@ -2746,6 +2746,93 @@ export interface paths {
|
|
|
2746
2746
|
patch?: never;
|
|
2747
2747
|
trace?: never;
|
|
2748
2748
|
};
|
|
2749
|
+
"/v1/egress": {
|
|
2750
|
+
parameters: {
|
|
2751
|
+
query?: never;
|
|
2752
|
+
header?: never;
|
|
2753
|
+
path?: never;
|
|
2754
|
+
cookie?: never;
|
|
2755
|
+
};
|
|
2756
|
+
/** @description Where the account stands for residential egress: whether it may send a sandbox's web traffic out through a residential address, what it still needs before it may, what that traffic has cost this month against its budget, and whether it is refused now. */
|
|
2757
|
+
get: operations["getEgress"];
|
|
2758
|
+
put?: never;
|
|
2759
|
+
post?: never;
|
|
2760
|
+
delete?: never;
|
|
2761
|
+
options?: never;
|
|
2762
|
+
head?: never;
|
|
2763
|
+
patch?: never;
|
|
2764
|
+
trace?: never;
|
|
2765
|
+
};
|
|
2766
|
+
"/v1/egress/use-case": {
|
|
2767
|
+
parameters: {
|
|
2768
|
+
query?: never;
|
|
2769
|
+
header?: never;
|
|
2770
|
+
path?: never;
|
|
2771
|
+
cookie?: never;
|
|
2772
|
+
};
|
|
2773
|
+
get?: never;
|
|
2774
|
+
/** @description Tells us what the account's sandboxes will use residential addresses for, in place of what it said before. It is said once for the whole account, covers all its sandboxes and templates, and we may refuse residential egress on it. With a plan of Fleet or larger and a card saved, the account may then turn it on for its sandboxes. */
|
|
2775
|
+
put: operations["setEgressUseCase"];
|
|
2776
|
+
post?: never;
|
|
2777
|
+
delete?: never;
|
|
2778
|
+
options?: never;
|
|
2779
|
+
head?: never;
|
|
2780
|
+
patch?: never;
|
|
2781
|
+
trace?: never;
|
|
2782
|
+
};
|
|
2783
|
+
"/v1/egress/budget": {
|
|
2784
|
+
parameters: {
|
|
2785
|
+
query?: never;
|
|
2786
|
+
header?: never;
|
|
2787
|
+
path?: never;
|
|
2788
|
+
cookie?: never;
|
|
2789
|
+
};
|
|
2790
|
+
get?: never;
|
|
2791
|
+
/** @description Sets the most the account's residential traffic costs in a month. Past it, its residential connections are refused, within a minute, until the month ends or the budget is raised. */
|
|
2792
|
+
put: operations["setEgressBudget"];
|
|
2793
|
+
post?: never;
|
|
2794
|
+
delete?: never;
|
|
2795
|
+
options?: never;
|
|
2796
|
+
head?: never;
|
|
2797
|
+
patch?: never;
|
|
2798
|
+
trace?: never;
|
|
2799
|
+
};
|
|
2800
|
+
"/v1/sandboxes/{id}/egress": {
|
|
2801
|
+
parameters: {
|
|
2802
|
+
query?: never;
|
|
2803
|
+
header?: never;
|
|
2804
|
+
path?: never;
|
|
2805
|
+
cookie?: never;
|
|
2806
|
+
};
|
|
2807
|
+
/** @description Where the sandbox's web traffic leaves: from its server, or through a residential address in a country. GET /v1/egress says whether the account's residential traffic is refused now. */
|
|
2808
|
+
get: operations["getSandboxEgress"];
|
|
2809
|
+
/** @description Sets where the sandbox's web traffic leaves, running or stopped, without a restart: new connections take it within seconds of the answer, and connections already open are not moved. residential: its TCP to ports 80 and 443 leaves through a residential address in country, at $3 a GB both directions, from the account's credits, and its UDP to port 443 is refused so HTTP/3 falls back to TCP; box: from its server again. Takes the action network.write. */
|
|
2810
|
+
put: operations["setSandboxEgress"];
|
|
2811
|
+
post?: never;
|
|
2812
|
+
delete?: never;
|
|
2813
|
+
options?: never;
|
|
2814
|
+
head?: never;
|
|
2815
|
+
patch?: never;
|
|
2816
|
+
trace?: never;
|
|
2817
|
+
};
|
|
2818
|
+
"/v1/templates/{id}/egress": {
|
|
2819
|
+
parameters: {
|
|
2820
|
+
query?: never;
|
|
2821
|
+
header?: never;
|
|
2822
|
+
path?: never;
|
|
2823
|
+
cookie?: never;
|
|
2824
|
+
};
|
|
2825
|
+
/** @description Where the web traffic of a sandbox made on the template leaves, unless its create says otherwise. */
|
|
2826
|
+
get: operations["getTemplateEgress"];
|
|
2827
|
+
/** @description Sets where the web traffic of each sandbox made on the template from now on leaves, unless its create says otherwise. Sandboxes already on it keep their own: PUT /v1/sandboxes/{id}/egress changes one. Takes the action network.write. */
|
|
2828
|
+
put: operations["setTemplateEgress"];
|
|
2829
|
+
post?: never;
|
|
2830
|
+
delete?: never;
|
|
2831
|
+
options?: never;
|
|
2832
|
+
head?: never;
|
|
2833
|
+
patch?: never;
|
|
2834
|
+
trace?: never;
|
|
2835
|
+
};
|
|
2749
2836
|
}
|
|
2750
2837
|
export type webhooks = Record<string, never>;
|
|
2751
2838
|
export interface components {
|
|
@@ -2793,7 +2880,7 @@ export interface components {
|
|
|
2793
2880
|
*/
|
|
2794
2881
|
feeMicros?: number;
|
|
2795
2882
|
/**
|
|
2796
|
-
* @description
|
|
2883
|
+
* @description On a 429 burst refusal: seconds until the same start costs no burst fee, as the meter falls. Null where waiting would not do: on running_limit_reached, or for a start larger than the plan's whole free burst. On a 503 admission_unavailable: 1. Also sent as Retry-After.
|
|
2797
2884
|
* @example 240
|
|
2798
2885
|
*/
|
|
2799
2886
|
retryAfterSeconds?: number | null;
|
|
@@ -3049,6 +3136,7 @@ export interface components {
|
|
|
3049
3136
|
metadata?: {
|
|
3050
3137
|
[key: string]: string;
|
|
3051
3138
|
};
|
|
3139
|
+
egress?: components["schemas"]["EgressInput"];
|
|
3052
3140
|
};
|
|
3053
3141
|
/** @description Addresses the sandbox may reach on top of its template's outbound rule. It is held to the two from its first boot, so it never runs open first. Left out, it has none of its own. The rule itself is its template's: PUT /v1/templates/{id}/network. PUT /v1/sandboxes/{id}/network changes its own addresses later, while it runs. A fork has its source's. Sending outbound here is refused with rule_on_template. Only where GET /v1/policy says networkPolicy. */
|
|
3054
3142
|
SandboxOwnNetworkInput: {
|
|
@@ -3060,6 +3148,26 @@ export interface components {
|
|
|
3060
3148
|
*/
|
|
3061
3149
|
allow: string[];
|
|
3062
3150
|
};
|
|
3151
|
+
/** @description Where its web traffic leaves, from its first boot. Left out, its template's (GET /v1/templates/{id}/egress); {"via": "box"} leaves from its server whatever its template says. PUT /v1/sandboxes/{id}/egress changes it later. A fork has its source's. residential asks that the account may use it: GET /v1/egress. Only where GET /v1/policy says residentialEgress. */
|
|
3152
|
+
EgressInput: {
|
|
3153
|
+
/**
|
|
3154
|
+
* @description box: from the server the sandbox is on, as every sandbox's does unless it asks otherwise, for nothing. residential: its TCP to ports 80 and 443 leaves through a residential address in country, charged at $3 a GB, both directions counted, from the account's credits; its UDP to port 443 is refused, so HTTP/3 falls back to TCP; other ports leave from its server as before.
|
|
3155
|
+
* @example residential
|
|
3156
|
+
* @enum {string}
|
|
3157
|
+
*/
|
|
3158
|
+
via: "box" | "residential";
|
|
3159
|
+
/**
|
|
3160
|
+
* @description With residential: the country the address is in, as two letters of ISO 3166-1, such as de or us. Not with box.
|
|
3161
|
+
* @example de
|
|
3162
|
+
*/
|
|
3163
|
+
country?: string;
|
|
3164
|
+
/**
|
|
3165
|
+
* @description With residential: sticky keeps one address for the sandbox for as long as it holds, as a person's browser would; rotating gives each connection another. Left out, sticky. Not with box.
|
|
3166
|
+
* @example sticky
|
|
3167
|
+
* @enum {string}
|
|
3168
|
+
*/
|
|
3169
|
+
session?: "sticky" | "rotating";
|
|
3170
|
+
};
|
|
3063
3171
|
SandboxList: {
|
|
3064
3172
|
sandboxes: components["schemas"]["Sandbox"][];
|
|
3065
3173
|
/** @description What to send as cursor, with the same sort and limit, for the sandboxes after these. Null when these are the last. */
|
|
@@ -4625,6 +4733,8 @@ export interface components {
|
|
|
4625
4733
|
networkPolicy: boolean;
|
|
4626
4734
|
/** @description Whether a variable can be kept out of its sandbox: set with hosts, its commands see a stand-in, and the proxy on the sandbox's server puts the value in on HTTPS requests to those hosts. False, a save with hosts answers 501 hidden_variables_unavailable, and a variable already kept out stays out. */
|
|
4627
4735
|
hiddenVariables: boolean;
|
|
4736
|
+
/** @description Whether a sandbox's web traffic can leave through a residential address, at $3 a GB: PUT /v1/sandboxes/{id}/egress, and egress on a create or a template. GET /v1/egress says whether the account may. False, asking for it answers 501 residential_egress_unavailable. */
|
|
4737
|
+
residentialEgress: boolean;
|
|
4628
4738
|
/** @description Whether a sandbox's CPU, memory, disk and network are read and kept: GET /v1/sandboxes/{id}/metrics and GET /v1/metrics. False, both answer 501 metrics_unavailable. GET /v1/metrics/running answers either way. */
|
|
4629
4739
|
metrics: boolean;
|
|
4630
4740
|
/** @description Whether an account can have its sandboxes' metrics and lifecycle events sent to a collector of its own, over OTLP/HTTP: GET, PUT and DELETE /v1/telemetry, and POST /v1/telemetry/test. Metrics are sent only where metrics is true as well. False, those calls answer 501 telemetry_unavailable. */
|
|
@@ -5377,6 +5487,66 @@ export interface components {
|
|
|
5377
5487
|
/** @description Always null: nothing raises an account but a change of plan. */
|
|
5378
5488
|
next: null;
|
|
5379
5489
|
};
|
|
5490
|
+
EgressAccount: {
|
|
5491
|
+
/** @description Whether this deployment offers residential egress at all, as GET /v1/policy says residentialEgress. */
|
|
5492
|
+
offered: boolean;
|
|
5493
|
+
/** @description Whether a sandbox of this account may go out residential now: offered, nothing missing, and not refused. */
|
|
5494
|
+
enabled: boolean;
|
|
5495
|
+
/** @description What the account still needs: plan, to be on Fleet ($100 a month) or a larger plan; card, a card saved; use_case, what its sandboxes will use residential addresses for, with PUT /v1/egress/use-case. */
|
|
5496
|
+
missing: ("plan" | "card" | "use_case")[];
|
|
5497
|
+
/** @description Set when we refused the account residential egress: its sandboxes' residential traffic is refused until we lift it. */
|
|
5498
|
+
refused: {
|
|
5499
|
+
reason: string;
|
|
5500
|
+
at: string;
|
|
5501
|
+
} | null;
|
|
5502
|
+
/** @description What the account told us its sandboxes will use residential addresses for, once for all of them, or null. */
|
|
5503
|
+
useCase: {
|
|
5504
|
+
text: string;
|
|
5505
|
+
submittedAt: string;
|
|
5506
|
+
} | null;
|
|
5507
|
+
/** @description What a GB of residential traffic costs, both directions counted, in millionths of a US dollar: 3000000 is $3. */
|
|
5508
|
+
microsPerGb: number;
|
|
5509
|
+
/** @description What its residential traffic has cost this month, in millionths of a US dollar. It is part of usedMicros in GET /v1/billing. */
|
|
5510
|
+
spentMicros: number;
|
|
5511
|
+
/** @description The most its residential traffic costs in a month. Past it, residential connections are refused until the month ends or the budget is raised. */
|
|
5512
|
+
budgetMicros: number;
|
|
5513
|
+
/** @description Whether the account set its budget. False: it is defaultBudgetMicros. */
|
|
5514
|
+
budgetSet: boolean;
|
|
5515
|
+
defaultBudgetMicros: number;
|
|
5516
|
+
/**
|
|
5517
|
+
* @description Why its residential connections are refused now, or null when they are not: refused, by us; out_of_credit, the credits ran out and an auto-reload did not cover it; budget_reached, this month's budget is spent; plan, the account is no longer on a plan that offers it. It is checked each minute, so a change shows within one.
|
|
5518
|
+
* @enum {string|null}
|
|
5519
|
+
*/
|
|
5520
|
+
blocked: "refused" | "out_of_credit" | "budget_reached" | "plan" | null;
|
|
5521
|
+
};
|
|
5522
|
+
EgressUseCase: {
|
|
5523
|
+
/**
|
|
5524
|
+
* @description What its sandboxes will use residential addresses for, in a few sentences: the sites, and why they need it.
|
|
5525
|
+
* @example Our agents test our customers' sign-up flows from the countries they sell in, behind Cloudflare Turnstile.
|
|
5526
|
+
*/
|
|
5527
|
+
useCase: string;
|
|
5528
|
+
};
|
|
5529
|
+
EgressBudget: {
|
|
5530
|
+
/**
|
|
5531
|
+
* @description The most the account's residential traffic costs in a month, in millionths of a US dollar: 0 refuses all of it. null gives it the default again, $50.
|
|
5532
|
+
* @example 50000000
|
|
5533
|
+
*/
|
|
5534
|
+
budgetMicros: number | null;
|
|
5535
|
+
};
|
|
5536
|
+
Egress: {
|
|
5537
|
+
/** @enum {string} */
|
|
5538
|
+
via: "box" | "residential";
|
|
5539
|
+
/**
|
|
5540
|
+
* @description With residential, the country, in lower case. Null with box.
|
|
5541
|
+
* @example de
|
|
5542
|
+
*/
|
|
5543
|
+
country: string | null;
|
|
5544
|
+
/**
|
|
5545
|
+
* @description With residential, sticky or rotating. Null with box.
|
|
5546
|
+
* @enum {string|null}
|
|
5547
|
+
*/
|
|
5548
|
+
session: "sticky" | "rotating" | null;
|
|
5549
|
+
};
|
|
5380
5550
|
};
|
|
5381
5551
|
responses: never;
|
|
5382
5552
|
parameters: never;
|
|
@@ -5718,6 +5888,17 @@ export interface operations {
|
|
|
5718
5888
|
"application/json": components["schemas"]["Error"];
|
|
5719
5889
|
};
|
|
5720
5890
|
};
|
|
5891
|
+
/** @description admission_unavailable: the create could not be written just now, and nothing was made or charged. Send the same request again, with the same Idempotency-Key, after Retry-After (1 second). */
|
|
5892
|
+
503: {
|
|
5893
|
+
headers: {
|
|
5894
|
+
/** @description Seconds to wait before sending it again: 1. */
|
|
5895
|
+
"Retry-After": string;
|
|
5896
|
+
[name: string]: unknown;
|
|
5897
|
+
};
|
|
5898
|
+
content: {
|
|
5899
|
+
"application/json": components["schemas"]["Error"];
|
|
5900
|
+
};
|
|
5901
|
+
};
|
|
5721
5902
|
};
|
|
5722
5903
|
};
|
|
5723
5904
|
summarizeSandboxes: {
|
|
@@ -7137,6 +7318,8 @@ export interface operations {
|
|
|
7137
7318
|
content: {
|
|
7138
7319
|
"application/json": {
|
|
7139
7320
|
name: string;
|
|
7321
|
+
/** @description true: the fork goes on from where the source was, with every process that ran in it running on and what they held in memory, instead of starting from a copy of its disk. It has its own address, machine id, SSH host key and random seed, and its processes still hold the source's environment, its token among them, until they end. A running source is paused while its memory is written, about a second for every 2 to 3 GiB; a source stopped with keepMemory gives the memory it kept and stays as it was. Only on sandboxes whose host offers it (501 driver_operation_unavailable elsewhere); a stopped source that kept no memory is 409 invalid_state. */
|
|
7322
|
+
memory?: boolean;
|
|
7140
7323
|
};
|
|
7141
7324
|
};
|
|
7142
7325
|
};
|
|
@@ -7150,7 +7333,7 @@ export interface operations {
|
|
|
7150
7333
|
"application/json": components["schemas"]["Sandbox"];
|
|
7151
7334
|
};
|
|
7152
7335
|
};
|
|
7153
|
-
/** @description Fork created and running: a new sandbox of the same size with a copy of what the source held, on the source's template, with the source's own secrets and addresses. It is held to that template's outbound rule as it is now, with those addresses on top, from its first boot. The source is left as it was. */
|
|
7336
|
+
/** @description Fork created and running: a new sandbox of the same size with a copy of what the source held, on the source's template, with the source's own secrets and addresses. It is held to that template's outbound rule as it is now, with those addresses on top, from its first boot. The source is left as it was. With memory, the fork's processes are the source's, running on. */
|
|
7154
7337
|
201: {
|
|
7155
7338
|
headers: {
|
|
7156
7339
|
[name: string]: unknown;
|
|
@@ -17688,4 +17871,384 @@ export interface operations {
|
|
|
17688
17871
|
};
|
|
17689
17872
|
};
|
|
17690
17873
|
};
|
|
17874
|
+
getEgress: {
|
|
17875
|
+
parameters: {
|
|
17876
|
+
query?: never;
|
|
17877
|
+
header?: never;
|
|
17878
|
+
path?: never;
|
|
17879
|
+
cookie?: never;
|
|
17880
|
+
};
|
|
17881
|
+
requestBody?: never;
|
|
17882
|
+
responses: {
|
|
17883
|
+
/** @description Where the account stands. */
|
|
17884
|
+
200: {
|
|
17885
|
+
headers: {
|
|
17886
|
+
[name: string]: unknown;
|
|
17887
|
+
};
|
|
17888
|
+
content: {
|
|
17889
|
+
"application/json": components["schemas"]["EgressAccount"];
|
|
17890
|
+
};
|
|
17891
|
+
};
|
|
17892
|
+
/** @description invalid_request. The key belongs to no account. */
|
|
17893
|
+
400: {
|
|
17894
|
+
headers: {
|
|
17895
|
+
[name: string]: unknown;
|
|
17896
|
+
};
|
|
17897
|
+
content: {
|
|
17898
|
+
"application/json": components["schemas"]["Error"];
|
|
17899
|
+
};
|
|
17900
|
+
};
|
|
17901
|
+
/** @description Missing or invalid API key. */
|
|
17902
|
+
401: {
|
|
17903
|
+
headers: {
|
|
17904
|
+
[name: string]: unknown;
|
|
17905
|
+
};
|
|
17906
|
+
content: {
|
|
17907
|
+
"application/json": components["schemas"]["Error"];
|
|
17908
|
+
};
|
|
17909
|
+
};
|
|
17910
|
+
};
|
|
17911
|
+
};
|
|
17912
|
+
setEgressUseCase: {
|
|
17913
|
+
parameters: {
|
|
17914
|
+
query?: never;
|
|
17915
|
+
header?: never;
|
|
17916
|
+
path?: never;
|
|
17917
|
+
cookie?: never;
|
|
17918
|
+
};
|
|
17919
|
+
requestBody: {
|
|
17920
|
+
content: {
|
|
17921
|
+
"application/json": components["schemas"]["EgressUseCase"];
|
|
17922
|
+
};
|
|
17923
|
+
};
|
|
17924
|
+
responses: {
|
|
17925
|
+
/** @description Kept, and the account as it stands now. */
|
|
17926
|
+
200: {
|
|
17927
|
+
headers: {
|
|
17928
|
+
[name: string]: unknown;
|
|
17929
|
+
};
|
|
17930
|
+
content: {
|
|
17931
|
+
"application/json": components["schemas"]["EgressAccount"];
|
|
17932
|
+
};
|
|
17933
|
+
};
|
|
17934
|
+
/** @description invalid_request: useCase is missing, shorter than 20 characters or longer than 2,000. The key belongs to no account. */
|
|
17935
|
+
400: {
|
|
17936
|
+
headers: {
|
|
17937
|
+
[name: string]: unknown;
|
|
17938
|
+
};
|
|
17939
|
+
content: {
|
|
17940
|
+
"application/json": components["schemas"]["Error"];
|
|
17941
|
+
};
|
|
17942
|
+
};
|
|
17943
|
+
/** @description Missing or invalid API key. */
|
|
17944
|
+
401: {
|
|
17945
|
+
headers: {
|
|
17946
|
+
[name: string]: unknown;
|
|
17947
|
+
};
|
|
17948
|
+
content: {
|
|
17949
|
+
"application/json": components["schemas"]["Error"];
|
|
17950
|
+
};
|
|
17951
|
+
};
|
|
17952
|
+
/** @description role_required: in a team, only an owner says this. egress_refused: we refused the account residential egress. */
|
|
17953
|
+
403: {
|
|
17954
|
+
headers: {
|
|
17955
|
+
[name: string]: unknown;
|
|
17956
|
+
};
|
|
17957
|
+
content: {
|
|
17958
|
+
"application/json": components["schemas"]["Error"];
|
|
17959
|
+
};
|
|
17960
|
+
};
|
|
17961
|
+
/** @description residential_egress_unavailable: GET /v1/policy says residentialEgress is false. */
|
|
17962
|
+
501: {
|
|
17963
|
+
headers: {
|
|
17964
|
+
[name: string]: unknown;
|
|
17965
|
+
};
|
|
17966
|
+
content: {
|
|
17967
|
+
"application/json": components["schemas"]["Error"];
|
|
17968
|
+
};
|
|
17969
|
+
};
|
|
17970
|
+
};
|
|
17971
|
+
};
|
|
17972
|
+
setEgressBudget: {
|
|
17973
|
+
parameters: {
|
|
17974
|
+
query?: never;
|
|
17975
|
+
header?: never;
|
|
17976
|
+
path?: never;
|
|
17977
|
+
cookie?: never;
|
|
17978
|
+
};
|
|
17979
|
+
requestBody: {
|
|
17980
|
+
content: {
|
|
17981
|
+
"application/json": components["schemas"]["EgressBudget"];
|
|
17982
|
+
};
|
|
17983
|
+
};
|
|
17984
|
+
responses: {
|
|
17985
|
+
/** @description The budget is set, and the account as it stands now. */
|
|
17986
|
+
200: {
|
|
17987
|
+
headers: {
|
|
17988
|
+
[name: string]: unknown;
|
|
17989
|
+
};
|
|
17990
|
+
content: {
|
|
17991
|
+
"application/json": components["schemas"]["EgressAccount"];
|
|
17992
|
+
};
|
|
17993
|
+
};
|
|
17994
|
+
/** @description invalid_request. The budget is not a whole number from 0 to 100000000000, or null, or the key belongs to no account. */
|
|
17995
|
+
400: {
|
|
17996
|
+
headers: {
|
|
17997
|
+
[name: string]: unknown;
|
|
17998
|
+
};
|
|
17999
|
+
content: {
|
|
18000
|
+
"application/json": components["schemas"]["Error"];
|
|
18001
|
+
};
|
|
18002
|
+
};
|
|
18003
|
+
/** @description Missing or invalid API key. */
|
|
18004
|
+
401: {
|
|
18005
|
+
headers: {
|
|
18006
|
+
[name: string]: unknown;
|
|
18007
|
+
};
|
|
18008
|
+
content: {
|
|
18009
|
+
"application/json": components["schemas"]["Error"];
|
|
18010
|
+
};
|
|
18011
|
+
};
|
|
18012
|
+
/** @description role_required: in a team, only an owner sets its budget. */
|
|
18013
|
+
403: {
|
|
18014
|
+
headers: {
|
|
18015
|
+
[name: string]: unknown;
|
|
18016
|
+
};
|
|
18017
|
+
content: {
|
|
18018
|
+
"application/json": components["schemas"]["Error"];
|
|
18019
|
+
};
|
|
18020
|
+
};
|
|
18021
|
+
/** @description residential_egress_unavailable: GET /v1/policy says residentialEgress is false. */
|
|
18022
|
+
501: {
|
|
18023
|
+
headers: {
|
|
18024
|
+
[name: string]: unknown;
|
|
18025
|
+
};
|
|
18026
|
+
content: {
|
|
18027
|
+
"application/json": components["schemas"]["Error"];
|
|
18028
|
+
};
|
|
18029
|
+
};
|
|
18030
|
+
};
|
|
18031
|
+
};
|
|
18032
|
+
getSandboxEgress: {
|
|
18033
|
+
parameters: {
|
|
18034
|
+
query?: never;
|
|
18035
|
+
header?: never;
|
|
18036
|
+
path: {
|
|
18037
|
+
id: string;
|
|
18038
|
+
};
|
|
18039
|
+
cookie?: never;
|
|
18040
|
+
};
|
|
18041
|
+
requestBody?: never;
|
|
18042
|
+
responses: {
|
|
18043
|
+
/** @description Where its web traffic leaves. */
|
|
18044
|
+
200: {
|
|
18045
|
+
headers: {
|
|
18046
|
+
[name: string]: unknown;
|
|
18047
|
+
};
|
|
18048
|
+
content: {
|
|
18049
|
+
"application/json": components["schemas"]["Egress"];
|
|
18050
|
+
};
|
|
18051
|
+
};
|
|
18052
|
+
/** @description Missing or invalid API key. */
|
|
18053
|
+
401: {
|
|
18054
|
+
headers: {
|
|
18055
|
+
[name: string]: unknown;
|
|
18056
|
+
};
|
|
18057
|
+
content: {
|
|
18058
|
+
"application/json": components["schemas"]["Error"];
|
|
18059
|
+
};
|
|
18060
|
+
};
|
|
18061
|
+
/** @description Not found. */
|
|
18062
|
+
404: {
|
|
18063
|
+
headers: {
|
|
18064
|
+
[name: string]: unknown;
|
|
18065
|
+
};
|
|
18066
|
+
content: {
|
|
18067
|
+
"application/json": components["schemas"]["Error"];
|
|
18068
|
+
};
|
|
18069
|
+
};
|
|
18070
|
+
};
|
|
18071
|
+
};
|
|
18072
|
+
setSandboxEgress: {
|
|
18073
|
+
parameters: {
|
|
18074
|
+
query?: never;
|
|
18075
|
+
header?: never;
|
|
18076
|
+
path: {
|
|
18077
|
+
id: string;
|
|
18078
|
+
};
|
|
18079
|
+
cookie?: never;
|
|
18080
|
+
};
|
|
18081
|
+
requestBody: {
|
|
18082
|
+
content: {
|
|
18083
|
+
"application/json": components["schemas"]["EgressInput"];
|
|
18084
|
+
};
|
|
18085
|
+
};
|
|
18086
|
+
responses: {
|
|
18087
|
+
/** @description Where its web traffic leaves from now on. */
|
|
18088
|
+
200: {
|
|
18089
|
+
headers: {
|
|
18090
|
+
[name: string]: unknown;
|
|
18091
|
+
};
|
|
18092
|
+
content: {
|
|
18093
|
+
"application/json": components["schemas"]["Egress"];
|
|
18094
|
+
};
|
|
18095
|
+
};
|
|
18096
|
+
/** @description invalid_request: residential without country, or country or session with box. Nothing was changed. */
|
|
18097
|
+
400: {
|
|
18098
|
+
headers: {
|
|
18099
|
+
[name: string]: unknown;
|
|
18100
|
+
};
|
|
18101
|
+
content: {
|
|
18102
|
+
"application/json": components["schemas"]["Error"];
|
|
18103
|
+
};
|
|
18104
|
+
};
|
|
18105
|
+
/** @description Missing or invalid API key. */
|
|
18106
|
+
401: {
|
|
18107
|
+
headers: {
|
|
18108
|
+
[name: string]: unknown;
|
|
18109
|
+
};
|
|
18110
|
+
content: {
|
|
18111
|
+
"application/json": components["schemas"]["Error"];
|
|
18112
|
+
};
|
|
18113
|
+
};
|
|
18114
|
+
/** @description egress_not_enabled: the account may not go out residential yet, and missing says what it lacks (GET /v1/egress). egress_refused: we refused it. Nothing was changed. */
|
|
18115
|
+
403: {
|
|
18116
|
+
headers: {
|
|
18117
|
+
[name: string]: unknown;
|
|
18118
|
+
};
|
|
18119
|
+
content: {
|
|
18120
|
+
"application/json": components["schemas"]["Error"];
|
|
18121
|
+
};
|
|
18122
|
+
};
|
|
18123
|
+
/** @description Not found. */
|
|
18124
|
+
404: {
|
|
18125
|
+
headers: {
|
|
18126
|
+
[name: string]: unknown;
|
|
18127
|
+
};
|
|
18128
|
+
content: {
|
|
18129
|
+
"application/json": components["schemas"]["Error"];
|
|
18130
|
+
};
|
|
18131
|
+
};
|
|
18132
|
+
/** @description residential_egress_unavailable: residential was asked for where GET /v1/policy says residentialEgress is false. Nothing was changed. */
|
|
18133
|
+
501: {
|
|
18134
|
+
headers: {
|
|
18135
|
+
[name: string]: unknown;
|
|
18136
|
+
};
|
|
18137
|
+
content: {
|
|
18138
|
+
"application/json": components["schemas"]["Error"];
|
|
18139
|
+
};
|
|
18140
|
+
};
|
|
18141
|
+
};
|
|
18142
|
+
};
|
|
18143
|
+
getTemplateEgress: {
|
|
18144
|
+
parameters: {
|
|
18145
|
+
query?: never;
|
|
18146
|
+
header?: never;
|
|
18147
|
+
path: {
|
|
18148
|
+
id: string;
|
|
18149
|
+
};
|
|
18150
|
+
cookie?: never;
|
|
18151
|
+
};
|
|
18152
|
+
requestBody?: never;
|
|
18153
|
+
responses: {
|
|
18154
|
+
/** @description Where a new sandbox's web traffic leaves. */
|
|
18155
|
+
200: {
|
|
18156
|
+
headers: {
|
|
18157
|
+
[name: string]: unknown;
|
|
18158
|
+
};
|
|
18159
|
+
content: {
|
|
18160
|
+
"application/json": components["schemas"]["Egress"];
|
|
18161
|
+
};
|
|
18162
|
+
};
|
|
18163
|
+
/** @description Missing or invalid API key. */
|
|
18164
|
+
401: {
|
|
18165
|
+
headers: {
|
|
18166
|
+
[name: string]: unknown;
|
|
18167
|
+
};
|
|
18168
|
+
content: {
|
|
18169
|
+
"application/json": components["schemas"]["Error"];
|
|
18170
|
+
};
|
|
18171
|
+
};
|
|
18172
|
+
/** @description Not found. */
|
|
18173
|
+
404: {
|
|
18174
|
+
headers: {
|
|
18175
|
+
[name: string]: unknown;
|
|
18176
|
+
};
|
|
18177
|
+
content: {
|
|
18178
|
+
"application/json": components["schemas"]["Error"];
|
|
18179
|
+
};
|
|
18180
|
+
};
|
|
18181
|
+
};
|
|
18182
|
+
};
|
|
18183
|
+
setTemplateEgress: {
|
|
18184
|
+
parameters: {
|
|
18185
|
+
query?: never;
|
|
18186
|
+
header?: never;
|
|
18187
|
+
path: {
|
|
18188
|
+
id: string;
|
|
18189
|
+
};
|
|
18190
|
+
cookie?: never;
|
|
18191
|
+
};
|
|
18192
|
+
requestBody: {
|
|
18193
|
+
content: {
|
|
18194
|
+
"application/json": components["schemas"]["EgressInput"];
|
|
18195
|
+
};
|
|
18196
|
+
};
|
|
18197
|
+
responses: {
|
|
18198
|
+
/** @description Where a new sandbox's web traffic leaves from now on. */
|
|
18199
|
+
200: {
|
|
18200
|
+
headers: {
|
|
18201
|
+
[name: string]: unknown;
|
|
18202
|
+
};
|
|
18203
|
+
content: {
|
|
18204
|
+
"application/json": components["schemas"]["Egress"];
|
|
18205
|
+
};
|
|
18206
|
+
};
|
|
18207
|
+
/** @description invalid_request: residential without country, or country or session with box. Nothing was changed. */
|
|
18208
|
+
400: {
|
|
18209
|
+
headers: {
|
|
18210
|
+
[name: string]: unknown;
|
|
18211
|
+
};
|
|
18212
|
+
content: {
|
|
18213
|
+
"application/json": components["schemas"]["Error"];
|
|
18214
|
+
};
|
|
18215
|
+
};
|
|
18216
|
+
/** @description Missing or invalid API key. */
|
|
18217
|
+
401: {
|
|
18218
|
+
headers: {
|
|
18219
|
+
[name: string]: unknown;
|
|
18220
|
+
};
|
|
18221
|
+
content: {
|
|
18222
|
+
"application/json": components["schemas"]["Error"];
|
|
18223
|
+
};
|
|
18224
|
+
};
|
|
18225
|
+
/** @description egress_not_enabled: the account may not go out residential yet, and missing says what it lacks (GET /v1/egress). egress_refused: we refused it. Nothing was changed. */
|
|
18226
|
+
403: {
|
|
18227
|
+
headers: {
|
|
18228
|
+
[name: string]: unknown;
|
|
18229
|
+
};
|
|
18230
|
+
content: {
|
|
18231
|
+
"application/json": components["schemas"]["Error"];
|
|
18232
|
+
};
|
|
18233
|
+
};
|
|
18234
|
+
/** @description Not found. */
|
|
18235
|
+
404: {
|
|
18236
|
+
headers: {
|
|
18237
|
+
[name: string]: unknown;
|
|
18238
|
+
};
|
|
18239
|
+
content: {
|
|
18240
|
+
"application/json": components["schemas"]["Error"];
|
|
18241
|
+
};
|
|
18242
|
+
};
|
|
18243
|
+
/** @description residential_egress_unavailable: residential was asked for where GET /v1/policy says residentialEgress is false. Nothing was changed. */
|
|
18244
|
+
501: {
|
|
18245
|
+
headers: {
|
|
18246
|
+
[name: string]: unknown;
|
|
18247
|
+
};
|
|
18248
|
+
content: {
|
|
18249
|
+
"application/json": components["schemas"]["Error"];
|
|
18250
|
+
};
|
|
18251
|
+
};
|
|
18252
|
+
};
|
|
18253
|
+
};
|
|
17691
18254
|
}
|
package/dist/sandbox.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { type Http } from "./http.js";
|
|
2
2
|
import { Secrets, type Template } from "./template.js";
|
|
3
|
-
import type { BrowserState, CreateSchedule, Schedule, ScheduleRun, UpdateSchedule, SshKey, SshState, Command, DesktopLink, DesktopScreenshot, DesktopState, EmailMessage, EmailMessageList, EmailMessageSummary, ExecResult, HostRoute, SandboxAutoStop, SandboxEmail, SandboxInfo, SandboxMetrics, SandboxNetworkDetail, SandboxOwnNetwork, SandboxTemplate, SandboxUsage, SendEmail, SetAutoStop, Size, Snapshot } from "./types.js";
|
|
3
|
+
import type { BrowserState, CreateSchedule, Schedule, ScheduleRun, UpdateSchedule, SshKey, SshState, Command, DesktopLink, DesktopScreenshot, DesktopState, EmailMessage, EmailMessageList, EmailMessageSummary, ExecResult, HostRoute, SandboxAutoStop, SandboxEmail, SandboxInfo, SandboxMetrics, SandboxNetworkDetail, SandboxOwnNetwork, SandboxTemplate, SandboxUsage, SendEmail, SetAutoStop, Size, Snapshot, Egress, EgressInput } from "./types.js";
|
|
4
4
|
/** A create answers when the machine is ready, usually in under a minute. The API says to allow it three. */
|
|
5
5
|
declare const CREATE_TIMEOUT_MS = 180000;
|
|
6
6
|
/** A list is the arguments exactly as given, with no shell. A string is a line of shell, run by `sh -c`. */
|
|
@@ -79,6 +79,14 @@ export interface CreateOptions extends BurstOptions {
|
|
|
79
79
|
* networkPolicy.
|
|
80
80
|
*/
|
|
81
81
|
network?: SandboxOwnNetwork;
|
|
82
|
+
/**
|
|
83
|
+
* Where its web traffic leaves, from its first boot: { via: "residential", country: "de" }
|
|
84
|
+
* sends its TCP to ports 80 and 443 out through a residential address in Germany, charged
|
|
85
|
+
* at $3 a GB from the account's credits. Left out, its template's; { via: "box" } leaves
|
|
86
|
+
* from its server whatever the template says. Residential asks that the account may use it:
|
|
87
|
+
* client.egress(). It takes a key with network.write. Only where policy() says residentialEgress.
|
|
88
|
+
*/
|
|
89
|
+
egress?: EgressInput;
|
|
82
90
|
/**
|
|
83
91
|
* OpenSSH public key lines let in as root as it is made, on top of the keys its template
|
|
84
92
|
* lets in. It turns nothing on: SSH is on as it is made only where its template says so,
|
|
@@ -522,6 +530,16 @@ export declare class Sandbox {
|
|
|
522
530
|
* affected. Only where policy() says networkPolicy.
|
|
523
531
|
*/
|
|
524
532
|
setNetwork(own: SandboxOwnNetwork): Promise<SandboxNetworkDetail>;
|
|
533
|
+
/** Where its web traffic leaves: from its server (box), or through a residential address in a country. */
|
|
534
|
+
egress(): Promise<Egress>;
|
|
535
|
+
/**
|
|
536
|
+
* Sets where its web traffic leaves, in place of what it had: { via: "box" }, or
|
|
537
|
+
* { via: "residential", country: "us", session: "rotating" }. New connections take it
|
|
538
|
+
* within seconds, without a restart, and connections already open are not moved.
|
|
539
|
+
* Residential asks that the account may use it: client.egress(). It takes a key with
|
|
540
|
+
* network.write. Only where policy() says residentialEgress.
|
|
541
|
+
*/
|
|
542
|
+
setEgress(egress: EgressInput): Promise<Egress>;
|
|
525
543
|
/**
|
|
526
544
|
* Runs a command and waits for it. A command that fails is still an answer: read
|
|
527
545
|
* exitCode. Every command starts fresh, as root in /root, so a cd or an export does not
|
|
@@ -564,8 +582,18 @@ export declare class Sandbox {
|
|
|
564
582
|
/**
|
|
565
583
|
* Copies it into a new sandbox, running, with the same disk. From then on the two share
|
|
566
584
|
* nothing. Nothing that was running here is started in the copy.
|
|
567
|
-
|
|
568
|
-
|
|
585
|
+
*
|
|
586
|
+
* With `memory: true` the copy goes on from where this one was instead: every process
|
|
587
|
+
* running on, with what it held in memory, under the copy's own address, machine id and SSH
|
|
588
|
+
* host key. Its processes still hold this sandbox's environment, its token among them, until
|
|
589
|
+
* they end. A running sandbox is paused while its memory is written, about a second for every
|
|
590
|
+
* 2 to 3 GiB; one stopped with `keepMemory` gives the memory it kept. Only on Firecracker
|
|
591
|
+
* boxes: elsewhere it throws `501 driver_operation_unavailable`, and for a stopped sandbox
|
|
592
|
+
* that kept no memory `409 invalid_state`. The copy is made in this sandbox's organization.
|
|
593
|
+
*/
|
|
594
|
+
fork(options?: Pick<CreateOptions, "name" | "idempotencyKey" | "timeoutMs" | "maxBurstFeeMicros" | "maxBurstWaitMs"> & {
|
|
595
|
+
memory?: boolean;
|
|
596
|
+
}): Promise<Sandbox>;
|
|
569
597
|
/** Destroys it and its disk for good. */
|
|
570
598
|
delete(): Promise<void>;
|
|
571
599
|
/** Keeps the sandbox as it is now, to roll back to or to make new sandboxes from. */
|
package/dist/sandbox.js
CHANGED
|
@@ -639,6 +639,20 @@ export class Sandbox {
|
|
|
639
639
|
this.info = { ...this.info, network: { outbound: detail.outbound, allow: detail.allow } };
|
|
640
640
|
return detail;
|
|
641
641
|
}
|
|
642
|
+
/** Where its web traffic leaves: from its server (box), or through a residential address in a country. */
|
|
643
|
+
async egress() {
|
|
644
|
+
return (await this.http.json({ method: "GET", path: `${this.path}/egress`, replay: true })).body;
|
|
645
|
+
}
|
|
646
|
+
/**
|
|
647
|
+
* Sets where its web traffic leaves, in place of what it had: { via: "box" }, or
|
|
648
|
+
* { via: "residential", country: "us", session: "rotating" }. New connections take it
|
|
649
|
+
* within seconds, without a restart, and connections already open are not moved.
|
|
650
|
+
* Residential asks that the account may use it: client.egress(). It takes a key with
|
|
651
|
+
* network.write. Only where policy() says residentialEgress.
|
|
652
|
+
*/
|
|
653
|
+
async setEgress(egress) {
|
|
654
|
+
return (await this.http.json({ method: "PUT", path: `${this.path}/egress`, body: egress, replay: true })).body;
|
|
655
|
+
}
|
|
642
656
|
/**
|
|
643
657
|
* Runs a command and waits for it. A command that fails is still an answer: read
|
|
644
658
|
* exitCode. Every command starts fresh, as root in /root, so a cd or an export does not
|
|
@@ -783,9 +797,17 @@ export class Sandbox {
|
|
|
783
797
|
/**
|
|
784
798
|
* Copies it into a new sandbox, running, with the same disk. From then on the two share
|
|
785
799
|
* nothing. Nothing that was running here is started in the copy.
|
|
800
|
+
*
|
|
801
|
+
* With `memory: true` the copy goes on from where this one was instead: every process
|
|
802
|
+
* running on, with what it held in memory, under the copy's own address, machine id and SSH
|
|
803
|
+
* host key. Its processes still hold this sandbox's environment, its token among them, until
|
|
804
|
+
* they end. A running sandbox is paused while its memory is written, about a second for every
|
|
805
|
+
* 2 to 3 GiB; one stopped with `keepMemory` gives the memory it kept. Only on Firecracker
|
|
806
|
+
* boxes: elsewhere it throws `501 driver_operation_unavailable`, and for a stopped sandbox
|
|
807
|
+
* that kept no memory `409 invalid_state`. The copy is made in this sandbox's organization.
|
|
786
808
|
*/
|
|
787
809
|
async fork(options = {}) {
|
|
788
|
-
const { info, burstFeeMicros } = await makeSandbox(this.http, `${this.path}/fork`, { name: options.name ?? made("sbx") }, options.idempotencyKey ?? made("sdk"), options.timeoutMs ?? CREATE_TIMEOUT_MS, options);
|
|
810
|
+
const { info, burstFeeMicros } = await makeSandbox(this.http, `${this.path}/fork`, { name: options.name ?? made("sbx"), ...(options.memory === true ? { memory: true } : {}) }, options.idempotencyKey ?? made("sdk"), options.timeoutMs ?? CREATE_TIMEOUT_MS, options);
|
|
789
811
|
return new Sandbox(this.http, info, burstFeeMicros);
|
|
790
812
|
}
|
|
791
813
|
/** Destroys it and its disk for good. */
|
package/dist/template.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { type Http } from "./http.js";
|
|
2
|
-
import type { HiddenVariable, NetworkRule, PlainVariable, SecretVariable, Size, SshKey, TemplateApplied, TemplateInfo, TemplateNetwork, TemplateSandbox, TemplateSsh, TemplateStart } from "./types.js";
|
|
2
|
+
import type { HiddenVariable, NetworkRule, PlainVariable, SecretVariable, Size, SshKey, TemplateApplied, TemplateInfo, TemplateNetwork, TemplateSandbox, TemplateSsh, TemplateStart, Egress, EgressInput } from "./types.js";
|
|
3
3
|
/**
|
|
4
4
|
* Secrets: a template's, or a sandbox's own. Variables are in the environment of every
|
|
5
5
|
* command run in a sandbox, and files are written into its work folder before each one.
|
|
@@ -130,6 +130,16 @@ export declare class Template {
|
|
|
130
130
|
* when it next starts, or now when apply() names it. Only where policy() says networkPolicy.
|
|
131
131
|
*/
|
|
132
132
|
setNetwork(rule: NetworkRule): Promise<TemplateNetwork>;
|
|
133
|
+
/** Where the web traffic of a sandbox made from it leaves. One that was never set is box: from its server. */
|
|
134
|
+
egress(): Promise<Egress>;
|
|
135
|
+
/**
|
|
136
|
+
* Sets where the web traffic of a sandbox made from it from now on leaves: { via: "box" },
|
|
137
|
+
* or { via: "residential", country: "de" }. A sandbox already made keeps its own, and one
|
|
138
|
+
* made with egress of its own has that. Residential asks that the account may use it:
|
|
139
|
+
* client.egress(). It takes a key with network.write. Only where policy() says
|
|
140
|
+
* residentialEgress.
|
|
141
|
+
*/
|
|
142
|
+
setEgress(egress: EgressInput): Promise<Egress>;
|
|
133
143
|
/** What a sandbox made from it is given for SSH as it is made: whether SSH is turned on, and the keys let in. */
|
|
134
144
|
ssh(): Promise<TemplateSsh>;
|
|
135
145
|
/**
|
package/dist/template.js
CHANGED
|
@@ -172,6 +172,20 @@ export class Template {
|
|
|
172
172
|
this.info = { ...this.info, network: set };
|
|
173
173
|
return set;
|
|
174
174
|
}
|
|
175
|
+
/** Where the web traffic of a sandbox made from it leaves. One that was never set is box: from its server. */
|
|
176
|
+
async egress() {
|
|
177
|
+
return (await this.http.json({ method: "GET", path: `${this.path}/egress`, replay: true })).body;
|
|
178
|
+
}
|
|
179
|
+
/**
|
|
180
|
+
* Sets where the web traffic of a sandbox made from it from now on leaves: { via: "box" },
|
|
181
|
+
* or { via: "residential", country: "de" }. A sandbox already made keeps its own, and one
|
|
182
|
+
* made with egress of its own has that. Residential asks that the account may use it:
|
|
183
|
+
* client.egress(). It takes a key with network.write. Only where policy() says
|
|
184
|
+
* residentialEgress.
|
|
185
|
+
*/
|
|
186
|
+
async setEgress(egress) {
|
|
187
|
+
return (await this.http.json({ method: "PUT", path: `${this.path}/egress`, body: egress, replay: true })).body;
|
|
188
|
+
}
|
|
175
189
|
/** What a sandbox made from it is given for SSH as it is made: whether SSH is turned on, and the keys let in. */
|
|
176
190
|
async ssh() {
|
|
177
191
|
return (await this.http.json({ method: "GET", path: `${this.path}/ssh`, replay: true })).body;
|
package/dist/types.d.ts
CHANGED
|
@@ -49,6 +49,16 @@ export type SandboxOwnNetwork = Schemas["SandboxOwnNetworkInput"];
|
|
|
49
49
|
export type TemplateNetwork = Schemas["TemplateNetwork"];
|
|
50
50
|
/** A rule to hold a template's sandboxes to: open, blocked, or allowlist with the IPv4 addresses and ranges in allow. */
|
|
51
51
|
export type NetworkRule = Schemas["TemplateNetworkInput"];
|
|
52
|
+
/** Where a sandbox's web traffic leaves: from its server (box), or through a residential address in a country. */
|
|
53
|
+
export type Egress = Schemas["Egress"];
|
|
54
|
+
/**
|
|
55
|
+
* Where to send a sandbox's web traffic out: { via: "box" }, or { via: "residential",
|
|
56
|
+
* country: "de", session?: "sticky" | "rotating" }. Residential is charged at $3 a GB, both
|
|
57
|
+
* directions counted, and only ports 80 and 443 over TCP go through it.
|
|
58
|
+
*/
|
|
59
|
+
export type EgressInput = Schemas["EgressInput"];
|
|
60
|
+
/** Whether the account may send sandboxes out residential, what it still needs, and what it has spent and may spend this month. */
|
|
61
|
+
export type EgressAccount = Schemas["EgressAccount"];
|
|
52
62
|
export type Size = SandboxInfo["size"];
|
|
53
63
|
/** What a command ended with. A command that failed is still an answer: read exitCode. */
|
|
54
64
|
export type ExecResult = Schemas["ExecResult"];
|
package/dist/version.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
/** This package's version, as package.json says it. A test holds the two to the same. */
|
|
2
|
-
export declare const VERSION = "0.
|
|
2
|
+
export declare const VERSION = "0.3.0";
|
package/dist/version.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
/** This package's version, as package.json says it. A test holds the two to the same. */
|
|
2
|
-
export const VERSION = "0.
|
|
2
|
+
export const VERSION = "0.3.0";
|
package/package.json
CHANGED