agental-sdk 0.3.1 → 0.5.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 +31 -10
- package/dist/client.d.ts +14 -15
- package/dist/client.js +17 -14
- package/dist/errors.d.ts +15 -3
- package/dist/errors.js +23 -7
- package/dist/http.d.ts +15 -0
- package/dist/http.js +30 -3
- package/dist/index.d.ts +3 -1
- package/dist/index.js +1 -0
- package/dist/openapi.d.ts +392 -8
- package/dist/sandbox.d.ts +17 -1
- package/dist/sandbox.js +22 -0
- package/dist/terminal.d.ts +113 -0
- package/dist/terminal.js +224 -0
- package/dist/types.d.ts +25 -5
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -175,6 +175,21 @@ await sandbox.ssh.off(); // its port is closed
|
|
|
175
175
|
|
|
176
176
|
`sandbox.ssh.get()` reads it and changes nothing, and `removeKey(id)` takes a key away. SSH stays on through a stop, a start and a move, and `address` is null while the sandbox is not running. The command's `agental ssh <sandbox-id>` does all of it in one go.
|
|
177
177
|
|
|
178
|
+
## Terminal
|
|
179
|
+
|
|
180
|
+
A login shell in the sandbox, as root in `/root`, over a WebSocket: no key and no port, as the console's Terminal tab has it.
|
|
181
|
+
|
|
182
|
+
```ts
|
|
183
|
+
const terminal = await sandbox.terminal({ cols: 120, rows: 32 });
|
|
184
|
+
terminal.write("cd /opt/agental && ls\n");
|
|
185
|
+
terminal.resize(132, 40); // as your own terminal's window changes
|
|
186
|
+
terminal.write("exit 3\n");
|
|
187
|
+
for await (const chunk of terminal) process.stdout.write(chunk); // Uint8Array, as the shell wrote it
|
|
188
|
+
const { exitCode, closeCode } = await terminal.exited; // 3, 1000
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
It needs a key with the `exec` action, and the sandbox running. It is opened with the runtime's own `WebSocket` (Node 22 and later, browsers, Deno, Bun); in Node 20 pass `new Agental({ WebSocket })` from the `ws` package. The API closes it when the shell ends (`closeCode` 1000, with `exitCode`), when the key or the sandbox no longer lets it be open (4003), after 30 minutes with nothing typed (4008), and when its sandbox stops answering (4011); `error` says why when the API did. `close()`, or leaving the `for await`, hangs the shell up, as an SSH session's end does: start what must outlive it with `nohup` or `setsid`. The command's `agental shell <sandbox-id>` opens one in your own terminal.
|
|
192
|
+
|
|
178
193
|
## Desktop
|
|
179
194
|
|
|
180
195
|
```ts
|
|
@@ -333,20 +348,26 @@ The free plan makes tiny and small sandboxes, the $100 plan medium ones too, and
|
|
|
333
348
|
|
|
334
349
|
## How many you run, and how fast you start them
|
|
335
350
|
|
|
336
|
-
Each plan runs so many small sandboxes at once, its running count, and starts so many at once for nothing, its free burst: a tiny counts half, a medium 2 and a large 4. The free plan runs 20 and bursts 20, though only 2 at once until the account has paid for something (`
|
|
351
|
+
Each plan runs so many small sandboxes at once, its running count, and starts so many at once for nothing, its free burst: a tiny counts half, a medium 2 and a large 4. The free plan runs 20 and bursts 20, though only 2 at once until the account has paid for something (`headroom().now.unpaid`, `prices().free.unpaidUnits`), the $100 plan 100 and 100, the $500 plan 600 and 200, the $2000 plan 2000 and 400; `prices().tiers` gives each plan's `runningUnits` and `freeBurstUnits`, and `burstFee` how fees are worked out. Each start adds its memory to a burst meter that halves every 15 minutes. Starting faster than the free burst is never refused for speed: it costs a burst fee, which grows with how far over the meter goes.
|
|
352
|
+
|
|
353
|
+
`headroom()` says how close the account runs to these limits: `now`, where it stands, and over a range (today, UTC, unless `from` and `to` say otherwise, 90 days at most) what it ran against its running count, each burst (a stretch when the meter was over the free burst, so every start in it paid a fee), what did not start and why, and how fast what started ran.
|
|
337
354
|
|
|
338
355
|
```ts
|
|
339
|
-
const
|
|
340
|
-
console.log(
|
|
341
|
-
console.log(
|
|
342
|
-
console.log(
|
|
356
|
+
const { now, atRunningCountMs, bursts, refused } = await agental.headroom();
|
|
357
|
+
console.log(now.runningMb / 4096, now.runningUnits); // small sandboxes running, of 100
|
|
358
|
+
console.log(now.freeNowMb / 4096); // small sandboxes you may start now for nothing
|
|
359
|
+
console.log(now.spentMicros, now.budgetMicros); // burst fees this month, and the most you spend on them
|
|
360
|
+
console.log(now.nextStart); // what one sandbox of each size would cost to start now
|
|
361
|
+
console.log(atRunningCountMs / 60_000); // minutes today at the running count
|
|
362
|
+
console.log(bursts[0]?.startedAt, bursts[0]?.endedAt); // the newest burst; endedAt is null while it goes on
|
|
363
|
+
console.log(refused.total, refused.byReason); // what did not start today: running_count, budget, fee_cap, room or other
|
|
343
364
|
|
|
344
|
-
//
|
|
345
|
-
const
|
|
346
|
-
console.log(
|
|
365
|
+
// The last week, read every hour.
|
|
366
|
+
const week = await agental.headroom({ from: new Date(Date.now() - 7 * 86_400_000), step: "hour" });
|
|
367
|
+
console.log(week.series.map((point) => point.peakRunningMb / 4096));
|
|
347
368
|
|
|
348
369
|
// Spend at most $10 a month on burst fees; 0 refuses every start that would cost one, null puts back the default ($50).
|
|
349
|
-
await agental.
|
|
370
|
+
await agental.setHeadroomBudget(10_000_000);
|
|
350
371
|
```
|
|
351
372
|
|
|
352
373
|
A create, fork or start takes `maxBurstFeeMicros`, the most it may pay, and the sandbox's `burstFeeMicros` says what it paid:
|
|
@@ -357,7 +378,7 @@ console.log(sandbox.burstFeeMicros); // 0 within the free burst
|
|
|
357
378
|
await sandbox.start({ maxBurstFeeMicros: 0, maxBurstWaitMs: 300_000 }); // free, waiting up to 5 minutes for it to be
|
|
358
379
|
```
|
|
359
380
|
|
|
360
|
-
Where `enforced` is true, a start is refused with an `ApiError` of status 429 and one of these codes. `feeMicros` says what it would have cost and `retryAfterSeconds` when it would cost nothing, or null when waiting would not help:
|
|
381
|
+
Where `now.enforced` is true, a start is refused with an `ApiError` of status 429 and one of these codes. `feeMicros` says what it would have cost and `retryAfterSeconds` when it would cost nothing, or null when waiting would not help; `refusedLastHour` how many creates and starts were refused with the same code in the last hour, this one with them, and `headroomUrl` the console's page that shows them all:
|
|
361
382
|
|
|
362
383
|
- `running_limit_reached`: the account already runs its plan's running count. Stop something first.
|
|
363
384
|
- `burst_fee_too_high`: the start would cost more than `maxBurstFeeMicros`.
|
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,
|
|
4
|
+
import type { AccountEmail, AccountExport, ApiKey, ApiKeyUsage, Billing, Headroom, HeadroomNow, HeadroomRange, Catalog, HostRoute, Invite, Me, Member, Organization, Region, AutoReload, Checkout, DataRetention, CreateApiKey, CreatedApiKey, MetricsAtMoment, Policy, Prices, RunningOverTime, SandboxSummary, SandboxJob, SandboxJobItem, SandboxJobPreview, 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. */
|
|
@@ -313,28 +313,27 @@ export declare class Agental {
|
|
|
313
313
|
/** The account's mail: the handle every address of its sandboxes carries, what its plan allows, and what it has had of that today. */
|
|
314
314
|
email(): Promise<AccountEmail>;
|
|
315
315
|
/**
|
|
316
|
-
*
|
|
317
|
-
* at once (runningUnits; a tiny counts half, a medium 2, a
|
|
318
|
-
* reads against the free burst, what it has spent on burst
|
|
319
|
-
* budget, and what one sandbox of each size would cost to start
|
|
320
|
-
*
|
|
316
|
+
* How close your account runs to its plan's limits. `now` is where it stands: how many small
|
|
317
|
+
* sandboxes it runs and may run at once (runningUnits; a tiny counts half, a medium 2, a
|
|
318
|
+
* large 4), what its burst meter reads against the free burst, what it has spent on burst
|
|
319
|
+
* fees this month against its budget, and what one sandbox of each size would cost to start
|
|
320
|
+
* now. Over the range, today (UTC) unless from and to say otherwise: what it ran against its
|
|
321
|
+
* running count (series, atRunningCountMs), each burst, what did not start and why
|
|
322
|
+
* (refused), and how fast what started ran (speed). A range covers 90 days at most.
|
|
321
323
|
*
|
|
322
|
-
* Where `enforced` is true, a create, fork or start past the running count throws an
|
|
324
|
+
* Where `now.enforced` is true, a create, fork or start past the running count throws an
|
|
323
325
|
* `ApiError` 429 `running_limit_reached`; one faster than the free burst costs a burst fee,
|
|
324
326
|
* and is refused with `burst_budget_reached` past the monthly budget.
|
|
325
|
-
* On the free plan, until the account has paid for something (`unpaid`), the running
|
|
326
|
-
* is `free.unpaidUnits` of prices(). Amounts are millionths of a US dollar.
|
|
327
|
+
* On the free plan, until the account has paid for something (`now.unpaid`), the running
|
|
328
|
+
* count is `free.unpaidUnits` of prices(). Amounts are millionths of a US dollar.
|
|
327
329
|
*/
|
|
328
|
-
|
|
329
|
-
size: Size;
|
|
330
|
-
count?: number;
|
|
331
|
-
}): Promise<Burst>;
|
|
330
|
+
headroom(range?: HeadroomRange): Promise<Headroom>;
|
|
332
331
|
/**
|
|
333
332
|
* Sets the most the account spends on burst fees in a month, in millionths of a US dollar:
|
|
334
333
|
* 0 refuses every start that would cost one. null gives it the default again,
|
|
335
|
-
* defaultBudgetMicros. It answers with the account
|
|
334
|
+
* defaultBudgetMicros. It answers with where the account stands now, as headroom().now.
|
|
336
335
|
*/
|
|
337
|
-
|
|
336
|
+
setHeadroomBudget(budgetMicros: number | null): Promise<HeadroomNow>;
|
|
338
337
|
/**
|
|
339
338
|
* Whether the account may send sandboxes out through residential addresses, and what it
|
|
340
339
|
* still needs: plan (Fleet or larger), card (one saved), use_case (setEgressUseCase()).
|
package/dist/client.js
CHANGED
|
@@ -431,29 +431,32 @@ export class Agental {
|
|
|
431
431
|
return (await this.http.json({ method: "GET", path: "/v1/email", replay: true })).body;
|
|
432
432
|
}
|
|
433
433
|
/**
|
|
434
|
-
*
|
|
435
|
-
* at once (runningUnits; a tiny counts half, a medium 2, a
|
|
436
|
-
* reads against the free burst, what it has spent on burst
|
|
437
|
-
* budget, and what one sandbox of each size would cost to start
|
|
438
|
-
*
|
|
434
|
+
* How close your account runs to its plan's limits. `now` is where it stands: how many small
|
|
435
|
+
* sandboxes it runs and may run at once (runningUnits; a tiny counts half, a medium 2, a
|
|
436
|
+
* large 4), what its burst meter reads against the free burst, what it has spent on burst
|
|
437
|
+
* fees this month against its budget, and what one sandbox of each size would cost to start
|
|
438
|
+
* now. Over the range, today (UTC) unless from and to say otherwise: what it ran against its
|
|
439
|
+
* running count (series, atRunningCountMs), each burst, what did not start and why
|
|
440
|
+
* (refused), and how fast what started ran (speed). A range covers 90 days at most.
|
|
439
441
|
*
|
|
440
|
-
* Where `enforced` is true, a create, fork or start past the running count throws an
|
|
442
|
+
* Where `now.enforced` is true, a create, fork or start past the running count throws an
|
|
441
443
|
* `ApiError` 429 `running_limit_reached`; one faster than the free burst costs a burst fee,
|
|
442
444
|
* and is refused with `burst_budget_reached` past the monthly budget.
|
|
443
|
-
* On the free plan, until the account has paid for something (`unpaid`), the running
|
|
444
|
-
* is `free.unpaidUnits` of prices(). Amounts are millionths of a US dollar.
|
|
445
|
+
* On the free plan, until the account has paid for something (`now.unpaid`), the running
|
|
446
|
+
* count is `free.unpaidUnits` of prices(). Amounts are millionths of a US dollar.
|
|
445
447
|
*/
|
|
446
|
-
async
|
|
447
|
-
const
|
|
448
|
-
|
|
448
|
+
async headroom(range = {}) {
|
|
449
|
+
const iso = (at) => (at instanceof Date ? at.toISOString() : at);
|
|
450
|
+
const query = { from: iso(range.from), to: iso(range.to), step: range.step };
|
|
451
|
+
return (await this.http.json({ method: "GET", path: "/v1/headroom", query, replay: true })).body;
|
|
449
452
|
}
|
|
450
453
|
/**
|
|
451
454
|
* Sets the most the account spends on burst fees in a month, in millionths of a US dollar:
|
|
452
455
|
* 0 refuses every start that would cost one. null gives it the default again,
|
|
453
|
-
* defaultBudgetMicros. It answers with the account
|
|
456
|
+
* defaultBudgetMicros. It answers with where the account stands now, as headroom().now.
|
|
454
457
|
*/
|
|
455
|
-
async
|
|
456
|
-
return (await this.http.json({ method: "PUT", path: "/v1/
|
|
458
|
+
async setHeadroomBudget(budgetMicros) {
|
|
459
|
+
return (await this.http.json({ method: "PUT", path: "/v1/headroom/budget", body: { budgetMicros }, replay: true })).body;
|
|
457
460
|
}
|
|
458
461
|
/**
|
|
459
462
|
* Whether the account may send sandboxes out through residential addresses, and what it
|
package/dist/errors.d.ts
CHANGED
|
@@ -21,21 +21,33 @@ export declare class ApiError extends AgentalError {
|
|
|
21
21
|
* size now, to send it again to with a new key. Empty when none has, and undefined on
|
|
22
22
|
* any other error.
|
|
23
23
|
*/
|
|
24
|
-
regionsWithRoom?: string[] | undefined,
|
|
24
|
+
regionsWithRoom?: string[] | undefined, refusal?: {
|
|
25
25
|
feeMicros?: number;
|
|
26
26
|
retryAfterSeconds?: number | null;
|
|
27
|
+
refusedLastHour?: number;
|
|
28
|
+
headroomUrl?: string;
|
|
27
29
|
});
|
|
28
30
|
/**
|
|
29
|
-
* On a start refused with 429 for its burst (see `BurstRefusalCode`): the burst fee it
|
|
31
|
+
* On a start refused with 429 or 409 for its burst (see `BurstRefusalCode`): the burst fee it
|
|
30
32
|
* would have cost, in millionths of a US dollar. Undefined on any other error.
|
|
31
33
|
*/
|
|
32
34
|
readonly feeMicros?: number;
|
|
33
35
|
/**
|
|
34
|
-
* On a start refused with 429 for its burst: seconds until the same start would cost no
|
|
36
|
+
* On a start refused with 429 or 409 for its burst: seconds until the same start would cost no
|
|
35
37
|
* burst fee. Null where waiting would not help: on running_limit_reached, or for a start
|
|
36
38
|
* larger than the plan's whole free burst. Undefined on any other error.
|
|
37
39
|
*/
|
|
38
40
|
readonly retryAfterSeconds?: number | null;
|
|
41
|
+
/**
|
|
42
|
+
* On a create or start refused with 429 or 409: how many of the account's creates and starts were
|
|
43
|
+
* refused with the same code in the last hour, this one with them. Undefined on any other error.
|
|
44
|
+
*/
|
|
45
|
+
readonly refusedLastHour?: number;
|
|
46
|
+
/**
|
|
47
|
+
* On a create or start refused with 429 or 409: the console's page where the account sees every
|
|
48
|
+
* refusal, as headroom() reads them. Undefined on any other error.
|
|
49
|
+
*/
|
|
50
|
+
readonly headroomUrl?: string;
|
|
39
51
|
}
|
|
40
52
|
/**
|
|
41
53
|
* Why a create, fork or start was refused with the status 429. running_limit_reached: the
|
package/dist/errors.js
CHANGED
|
@@ -19,29 +19,45 @@ export class ApiError extends AgentalError {
|
|
|
19
19
|
* size now, to send it again to with a new key. Empty when none has, and undefined on
|
|
20
20
|
* any other error.
|
|
21
21
|
*/
|
|
22
|
-
regionsWithRoom,
|
|
22
|
+
regionsWithRoom, refusal) {
|
|
23
23
|
super(message);
|
|
24
24
|
this.status = status;
|
|
25
25
|
this.code = code;
|
|
26
26
|
this.regionsWithRoom = regionsWithRoom;
|
|
27
|
-
if (
|
|
28
|
-
this.feeMicros =
|
|
27
|
+
if (refusal?.feeMicros !== undefined) {
|
|
28
|
+
this.feeMicros = refusal.feeMicros;
|
|
29
29
|
}
|
|
30
|
-
if (
|
|
31
|
-
this.retryAfterSeconds =
|
|
30
|
+
if (refusal?.retryAfterSeconds !== undefined) {
|
|
31
|
+
this.retryAfterSeconds = refusal.retryAfterSeconds;
|
|
32
|
+
}
|
|
33
|
+
if (refusal?.refusedLastHour !== undefined) {
|
|
34
|
+
this.refusedLastHour = refusal.refusedLastHour;
|
|
35
|
+
}
|
|
36
|
+
if (refusal?.headroomUrl !== undefined) {
|
|
37
|
+
this.headroomUrl = refusal.headroomUrl;
|
|
32
38
|
}
|
|
33
39
|
}
|
|
34
40
|
/**
|
|
35
|
-
* On a start refused with 429 for its burst (see `BurstRefusalCode`): the burst fee it
|
|
41
|
+
* On a start refused with 429 or 409 for its burst (see `BurstRefusalCode`): the burst fee it
|
|
36
42
|
* would have cost, in millionths of a US dollar. Undefined on any other error.
|
|
37
43
|
*/
|
|
38
44
|
feeMicros;
|
|
39
45
|
/**
|
|
40
|
-
* On a start refused with 429 for its burst: seconds until the same start would cost no
|
|
46
|
+
* On a start refused with 429 or 409 for its burst: seconds until the same start would cost no
|
|
41
47
|
* burst fee. Null where waiting would not help: on running_limit_reached, or for a start
|
|
42
48
|
* larger than the plan's whole free burst. Undefined on any other error.
|
|
43
49
|
*/
|
|
44
50
|
retryAfterSeconds;
|
|
51
|
+
/**
|
|
52
|
+
* On a create or start refused with 429 or 409: how many of the account's creates and starts were
|
|
53
|
+
* refused with the same code in the last hour, this one with them. Undefined on any other error.
|
|
54
|
+
*/
|
|
55
|
+
refusedLastHour;
|
|
56
|
+
/**
|
|
57
|
+
* On a create or start refused with 429 or 409: the console's page where the account sees every
|
|
58
|
+
* refusal, as headroom() reads them. Undefined on any other error.
|
|
59
|
+
*/
|
|
60
|
+
headroomUrl;
|
|
45
61
|
}
|
|
46
62
|
/**
|
|
47
63
|
* Something in front of the API answered, not the API: a 502, a 504, a 52x, or any error
|
package/dist/http.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { WebSocketConstructor } from "./terminal.js";
|
|
1
2
|
export declare const DEFAULT_BASE_URL = "https://agental.io";
|
|
2
3
|
export interface AgentalOptions {
|
|
3
4
|
/**
|
|
@@ -15,6 +16,11 @@ export interface AgentalOptions {
|
|
|
15
16
|
retryDelayMs?: number;
|
|
16
17
|
/** How often something that is waited for is looked at, in milliseconds. Default 2000. */
|
|
17
18
|
pollIntervalMs?: number;
|
|
19
|
+
/**
|
|
20
|
+
* What a sandbox's terminal is opened with. Left out, it is the runtime's own WebSocket: in
|
|
21
|
+
* Node 22 and later, browsers, Deno and Bun. In Node 20, pass WebSocket from the ws package.
|
|
22
|
+
*/
|
|
23
|
+
WebSocket?: WebSocketConstructor;
|
|
18
24
|
}
|
|
19
25
|
export interface Call {
|
|
20
26
|
method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
|
|
@@ -42,7 +48,16 @@ export declare class Http {
|
|
|
42
48
|
private readonly fetch;
|
|
43
49
|
private readonly maxRetries;
|
|
44
50
|
private readonly retryDelayMs;
|
|
51
|
+
private readonly webSocket;
|
|
45
52
|
constructor(options?: AgentalOptions);
|
|
53
|
+
/** The WebSocket a terminal is opened with: the one given, else the runtime's own. */
|
|
54
|
+
get WebSocket(): WebSocketConstructor;
|
|
55
|
+
/**
|
|
56
|
+
* The ws: or wss: URL of a path on the API's own address, as a terminal's WebSocket is opened
|
|
57
|
+
* on it. Only a path is taken, so that no answer can send the WebSocket, and the ticket in
|
|
58
|
+
* it, to another host.
|
|
59
|
+
*/
|
|
60
|
+
webSocketUrl(path: string): string;
|
|
46
61
|
/** The answer to a request that worked. One that did not is thrown, after it was sent again if that was safe. */
|
|
47
62
|
send(call: Call): Promise<Response>;
|
|
48
63
|
/** The JSON a request was answered with, and the status and headers it came with. */
|
package/dist/http.js
CHANGED
|
@@ -64,6 +64,7 @@ export class Http {
|
|
|
64
64
|
fetch;
|
|
65
65
|
maxRetries;
|
|
66
66
|
retryDelayMs;
|
|
67
|
+
webSocket;
|
|
67
68
|
constructor(options = {}) {
|
|
68
69
|
let apiKey = options.apiKey ?? environment("AGENTAL_API_KEY");
|
|
69
70
|
let baseUrl = options.baseUrl ?? environment("AGENTAL_API_URL");
|
|
@@ -84,6 +85,30 @@ export class Http {
|
|
|
84
85
|
this.maxRetries = options.maxRetries ?? 3;
|
|
85
86
|
this.retryDelayMs = options.retryDelayMs ?? 1000;
|
|
86
87
|
this.pollIntervalMs = options.pollIntervalMs ?? 2000;
|
|
88
|
+
this.webSocket = options.WebSocket;
|
|
89
|
+
}
|
|
90
|
+
/** The WebSocket a terminal is opened with: the one given, else the runtime's own. */
|
|
91
|
+
get WebSocket() {
|
|
92
|
+
const found = this.webSocket ?? globalThis.WebSocket;
|
|
93
|
+
if (!found) {
|
|
94
|
+
throw new AgentalError("This runtime has no WebSocket, which a terminal is opened with. Use Node 22 or later, or pass new Agental({ WebSocket }) with WebSocket from the ws package.");
|
|
95
|
+
}
|
|
96
|
+
return found;
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* The ws: or wss: URL of a path on the API's own address, as a terminal's WebSocket is opened
|
|
100
|
+
* on it. Only a path is taken, so that no answer can send the WebSocket, and the ticket in
|
|
101
|
+
* it, to another host.
|
|
102
|
+
*/
|
|
103
|
+
webSocketUrl(path) {
|
|
104
|
+
if (!path.startsWith("/") || path.startsWith("//") || /[\\\s]/.test(path)) {
|
|
105
|
+
throw new AgentalError(`The API gave the terminal a path that is not one on its own address: ${JSON.stringify(path.slice(0, 200))}.`);
|
|
106
|
+
}
|
|
107
|
+
const url = new URL(this.baseUrl);
|
|
108
|
+
if (url.protocol !== "https:" && url.protocol !== "http:") {
|
|
109
|
+
throw new AgentalError(`A terminal is opened on an http: or https: API, not ${url.protocol}.`);
|
|
110
|
+
}
|
|
111
|
+
return `${url.origin.replace(/^http/, "ws")}${url.pathname.replace(/\/+$/, "")}${path}`;
|
|
87
112
|
}
|
|
88
113
|
/** The answer to a request that worked. One that did not is thrown, after it was sent again if that was safe. */
|
|
89
114
|
async send(call) {
|
|
@@ -221,14 +246,16 @@ async function errorOf(response) {
|
|
|
221
246
|
const body = parsed(await response.text().catch(() => ""));
|
|
222
247
|
const error = body && typeof body === "object" ? body.error : null;
|
|
223
248
|
if (error && typeof error === "object") {
|
|
224
|
-
const { code, message, regionsWithRoom, feeMicros, retryAfterSeconds } = error;
|
|
249
|
+
const { code, message, regionsWithRoom, feeMicros, retryAfterSeconds, refusedLastHour, headroomUrl } = error;
|
|
225
250
|
if (typeof code === "string" && typeof message === "string") {
|
|
226
251
|
const regions = Array.isArray(regionsWithRoom) ? regionsWithRoom.filter((one) => typeof one === "string") : undefined;
|
|
227
|
-
const
|
|
252
|
+
const refusal = {
|
|
228
253
|
...(typeof feeMicros === "number" ? { feeMicros } : {}),
|
|
229
254
|
...(typeof retryAfterSeconds === "number" || retryAfterSeconds === null ? { retryAfterSeconds } : {}),
|
|
255
|
+
...(typeof refusedLastHour === "number" ? { refusedLastHour } : {}),
|
|
256
|
+
...(typeof headroomUrl === "string" ? { headroomUrl } : {}),
|
|
230
257
|
};
|
|
231
|
-
return new ApiError(response.status, code, message, regions,
|
|
258
|
+
return new ApiError(response.status, code, message, regions, refusal);
|
|
232
259
|
}
|
|
233
260
|
}
|
|
234
261
|
return new ProxyError(response.status);
|
package/dist/index.d.ts
CHANGED
|
@@ -4,7 +4,9 @@ export type { BurstRefusalCode } from "./errors.js";
|
|
|
4
4
|
export type { AgentalOptions } from "./http.js";
|
|
5
5
|
export { Browser, Commands, Desktop, Email, Files, Sandbox, Schedules, Ssh } from "./sandbox.js";
|
|
6
6
|
export { Secrets, Template, Templates } from "./template.js";
|
|
7
|
+
export { Terminal, TERMINAL_CLOSE, TERMINAL_PROTOCOL } from "./terminal.js";
|
|
8
|
+
export type { TerminalExit, TerminalOptions, WebSocketConstructor, WebSocketLike } from "./terminal.js";
|
|
7
9
|
export type { TemplateChanges } from "./template.js";
|
|
8
10
|
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,
|
|
11
|
+
export type { AccountEmail, ApiKey, ApiKeyAction, ApiKeyPreset, ApiKeyUsage, Billing, BrowserState, BurstFee, BurstQuote, Headroom, HeadroomNow, HeadroomRange, HeadroomStep, 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
12
|
export { verifyWebhook } from "./webhooks.js";
|
package/dist/index.js
CHANGED
|
@@ -2,4 +2,5 @@ export { Agental } from "./client.js";
|
|
|
2
2
|
export { AgentalError, ApiError, ConnectionError, ProxyError, TimeoutError } from "./errors.js";
|
|
3
3
|
export { Browser, Commands, Desktop, Email, Files, Sandbox, Schedules, Ssh } from "./sandbox.js";
|
|
4
4
|
export { Secrets, Template, Templates } from "./template.js";
|
|
5
|
+
export { Terminal, TERMINAL_CLOSE, TERMINAL_PROTOCOL } from "./terminal.js";
|
|
5
6
|
export { verifyWebhook } from "./webhooks.js";
|