agental 0.1.0 → 0.2.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 +5 -536
- package/bin/agental.js +1 -1
- package/dist/cli.js +20 -20
- package/package.json +8 -26
- package/dist/client.d.ts +0 -321
- package/dist/client.js +0 -451
- package/dist/errors.d.ts +0 -62
- package/dist/errors.js +0 -65
- package/dist/http.d.ts +0 -69
- package/dist/http.js +0 -246
- package/dist/index.d.ts +0 -10
- package/dist/index.js +0 -5
- package/dist/openapi.d.ts +0 -17070
- package/dist/openapi.js +0 -5
- package/dist/sandbox.d.ts +0 -605
- package/dist/sandbox.js +0 -846
- package/dist/template.d.ts +0 -183
- package/dist/template.js +0 -261
- package/dist/types.d.ts +0 -198
- package/dist/types.js +0 -1
- package/dist/version.d.ts +0 -2
- package/dist/version.js +0 -2
- package/dist/webhooks.d.ts +0 -6
- package/dist/webhooks.js +0 -16
package/dist/template.d.ts
DELETED
|
@@ -1,183 +0,0 @@
|
|
|
1
|
-
import { type Http } from "./http.js";
|
|
2
|
-
import type { HiddenVariable, NetworkRule, PlainVariable, SecretVariable, Size, SshKey, TemplateApplied, TemplateInfo, TemplateNetwork, TemplateRepo, TemplateSandbox, TemplateSsh, TemplateStart } from "./types.js";
|
|
3
|
-
/**
|
|
4
|
-
* Secrets: a template's, or a sandbox's own. Variables are in the environment of every
|
|
5
|
-
* command run in a sandbox, and files are written into its work folder before each one.
|
|
6
|
-
* A sandbox's own come on top of its template's: where both name the same variable or
|
|
7
|
-
* path, its own is used. Values are read one at a time. A variable kept out of the sandbox
|
|
8
|
-
* is in the environment as its stand-in, and its value is never given back.
|
|
9
|
-
*/
|
|
10
|
-
export declare class Secrets {
|
|
11
|
-
private readonly http;
|
|
12
|
-
private readonly path;
|
|
13
|
-
constructor(http: Http, path: string);
|
|
14
|
-
/** The names of the variables. hidden() says which of them are kept out of the sandbox. */
|
|
15
|
-
variables(): Promise<string[]>;
|
|
16
|
-
/** The names of the variables kept out of the sandbox. */
|
|
17
|
-
hidden(): Promise<string[]>;
|
|
18
|
-
/**
|
|
19
|
-
* One variable's value. A variable kept out of the sandbox has none to give, and is
|
|
20
|
-
* thrown as an AgentalError: variable() gives its hosts and its stand-in.
|
|
21
|
-
*/
|
|
22
|
-
get(name: string): Promise<string>;
|
|
23
|
-
/** One variable: a plain one with its value, or one kept out of the sandbox with its hosts and its stand-in. hidden says which. */
|
|
24
|
-
variable(name: string): Promise<SecretVariable>;
|
|
25
|
-
/**
|
|
26
|
-
* Sets a variable, and gives it as it is kept. With hosts it is kept out of the sandbox:
|
|
27
|
-
* its commands see a stand-in, and the proxy on the sandbox's server puts the value in
|
|
28
|
-
* place of the stand-in on HTTPS requests to those hosts, and nowhere else. Its stand-in
|
|
29
|
-
* stays the same when its value is replaced. Without hosts it is plain, and its commands
|
|
30
|
-
* read its value: one kept out that is set without hosts is plain from then on. A plain
|
|
31
|
-
* one may be empty: delete removes a variable. Hosts are names such as api.github.com, or
|
|
32
|
-
* *.example.com for every name under example.com, 1 to 10 of them, and only where
|
|
33
|
-
* policy() says hiddenVariables. They do not open the template's outbound rule.
|
|
34
|
-
*/
|
|
35
|
-
set(name: string, value: string, options: {
|
|
36
|
-
hosts: string[];
|
|
37
|
-
}): Promise<HiddenVariable>;
|
|
38
|
-
set(name: string, value: string, options?: {
|
|
39
|
-
hosts?: undefined;
|
|
40
|
-
}): Promise<PlainVariable>;
|
|
41
|
-
set(name: string, value: string, options?: {
|
|
42
|
-
hosts?: string[];
|
|
43
|
-
}): Promise<SecretVariable>;
|
|
44
|
-
/**
|
|
45
|
-
* Narrows the hosts a variable kept out of the sandbox is sent to, in place of the ones it
|
|
46
|
-
* had, without sending its value again. Its value and its stand-in stay as they are. Each
|
|
47
|
-
* host has to be one it is sent to now, or under one of its wildcards: a new one is refused
|
|
48
|
-
* with hosts_widened, and needs set() with the value. A plain variable is refused with
|
|
49
|
-
* not_hidden: set it with its value and hosts to keep it out.
|
|
50
|
-
*/
|
|
51
|
-
setHosts(name: string, hosts: string[]): Promise<HiddenVariable>;
|
|
52
|
-
delete(name: string): Promise<void>;
|
|
53
|
-
/** The paths of the files, relative to the work folder. */
|
|
54
|
-
files(): Promise<string[]>;
|
|
55
|
-
/** What one file holds. */
|
|
56
|
-
readFile(path: string): Promise<string>;
|
|
57
|
-
/** Sets a file, and gives the path as it is kept, written one way. */
|
|
58
|
-
writeFile(path: string, text: string): Promise<string>;
|
|
59
|
-
/** Stops writing a file. A copy already written to a sandbox's disk stays there. */
|
|
60
|
-
deleteFile(path: string): Promise<void>;
|
|
61
|
-
private listed;
|
|
62
|
-
private variablePath;
|
|
63
|
-
}
|
|
64
|
-
/**
|
|
65
|
-
* A template: what a sandbox is made as and held to, under one name. Its start says the
|
|
66
|
-
* size of a sandbox made from it, what it starts from and how long it runs after each
|
|
67
|
-
* start, its secrets are what every sandbox on it gets, and its outbound rule is what every
|
|
68
|
-
* sandbox on it may reach. A sandbox takes a change to its secrets and its rule when it
|
|
69
|
-
* next starts, or at once when apply() names it.
|
|
70
|
-
*/
|
|
71
|
-
/** What Template.update() changes. Left out, a field is left as it is. */
|
|
72
|
-
export interface TemplateChanges {
|
|
73
|
-
name?: string;
|
|
74
|
-
/** Its tags, in place of the ones it has. */
|
|
75
|
-
tags?: string[];
|
|
76
|
-
/** Merged into its metadata. null takes a key away. */
|
|
77
|
-
metadata?: Record<string, string | null>;
|
|
78
|
-
}
|
|
79
|
-
export declare class Template {
|
|
80
|
-
private readonly http;
|
|
81
|
-
readonly secrets: Secrets;
|
|
82
|
-
/** The template as it was last read. refresh() reads it again. */
|
|
83
|
-
info: TemplateInfo;
|
|
84
|
-
private readonly path;
|
|
85
|
-
constructor(http: Http, info: TemplateInfo);
|
|
86
|
-
get id(): string;
|
|
87
|
-
get name(): string;
|
|
88
|
-
/** Whether it is the account's default, which a sandbox is on when none is chosen. */
|
|
89
|
-
get isDefault(): boolean;
|
|
90
|
-
refresh(): Promise<this>;
|
|
91
|
-
rename(name: string): Promise<this>;
|
|
92
|
-
/** Its tags, which every sandbox on it is shown with too. */
|
|
93
|
-
get tags(): string[];
|
|
94
|
-
/** Its metadata, which every sandbox on it has too, under the sandbox's own value for a key. */
|
|
95
|
-
get metadata(): Record<string, string>;
|
|
96
|
-
/**
|
|
97
|
-
* Changes its name, its tags or its metadata. tags are put in place of the ones it has,
|
|
98
|
-
* and metadata is merged in, null taking a key away. Every sandbox on it is shown the
|
|
99
|
-
* change at once.
|
|
100
|
-
*/
|
|
101
|
-
update(changes: TemplateChanges): Promise<this>;
|
|
102
|
-
/** Gives it a tag, and so every sandbox on it. One it has already is left as it is. */
|
|
103
|
-
addTag(tag: string): Promise<this>;
|
|
104
|
-
/** Takes a tag away. One it does not have is nothing to take. */
|
|
105
|
-
removeTag(tag: string): Promise<this>;
|
|
106
|
-
/** Deletes it. One that sandboxes are on is refused: put them on another template first. */
|
|
107
|
-
delete(): Promise<void>;
|
|
108
|
-
/** What a sandbox made from it starts as. */
|
|
109
|
-
start(): Promise<TemplateStart>;
|
|
110
|
-
/**
|
|
111
|
-
* Sets what a sandbox made from it starts as, from now on: its size, the snapshot it starts
|
|
112
|
-
* from, and how many seconds it runs after each start before it is stopped, 60 at the
|
|
113
|
-
* least. snapshotId left out or null is a new machine. ttlSeconds left out stays as it was,
|
|
114
|
-
* and null is the deployment's default. One over maxTtlSeconds of policy() is refused with
|
|
115
|
-
* ttl_too_long. Sandboxes made before keep their size, their disk
|
|
116
|
-
* and their time limit.
|
|
117
|
-
*/
|
|
118
|
-
setStart(start: {
|
|
119
|
-
size: Size;
|
|
120
|
-
snapshotId?: string | null;
|
|
121
|
-
ttlSeconds?: number | null;
|
|
122
|
-
}): Promise<TemplateStart>;
|
|
123
|
-
/** The repository it links to, for reference. Nothing is cloned. */
|
|
124
|
-
repo(): Promise<TemplateRepo | null>;
|
|
125
|
-
setRepo(repo: {
|
|
126
|
-
name: string;
|
|
127
|
-
url: string;
|
|
128
|
-
}): Promise<TemplateRepo>;
|
|
129
|
-
removeRepo(): Promise<void>;
|
|
130
|
-
/** What a sandbox on it may reach outside itself, before the addresses of its own. One that was never set is open. */
|
|
131
|
-
network(): Promise<TemplateNetwork>;
|
|
132
|
-
/**
|
|
133
|
-
* Sets what a sandbox on it may reach outside itself, in place of the rule it had:
|
|
134
|
-
* { outbound: "open" }, { outbound: "blocked" }, or { outbound: "allowlist", allow: [...] }
|
|
135
|
-
* with every address it lets out to. A sandbox is held to it with its own addresses on
|
|
136
|
-
* top. One made from it is held to it from its first boot, and one already on it takes it
|
|
137
|
-
* when it next starts, or now when apply() names it. Only where policy() says networkPolicy.
|
|
138
|
-
*/
|
|
139
|
-
setNetwork(rule: NetworkRule): Promise<TemplateNetwork>;
|
|
140
|
-
/** What a sandbox made from it is given for SSH as it is made: whether SSH is turned on, and the keys let in. */
|
|
141
|
-
ssh(): Promise<TemplateSsh>;
|
|
142
|
-
/**
|
|
143
|
-
* Turns SSH on for every sandbox made from it from now on, as Sandbox.ssh.on() would as it
|
|
144
|
-
* is made. A sandbox already made is not changed, and no key is let in: addSshKey() does
|
|
145
|
-
* that. Only where policy() says ssh.
|
|
146
|
-
*/
|
|
147
|
-
sshOn(): Promise<TemplateSsh>;
|
|
148
|
-
/** A sandbox made from it from now on has SSH off as it is made. Sandboxes already made, and the keys, are left as they are. */
|
|
149
|
-
sshOff(): Promise<TemplateSsh>;
|
|
150
|
-
/** Lets a public key, one line as in an authorized keys file, in as root to every sandbox made from it from now on. Sandboxes already made are not changed. */
|
|
151
|
-
addSshKey(publicKey: string): Promise<SshKey>;
|
|
152
|
-
/**
|
|
153
|
-
* Takes a key, by its id, out of what the sandboxes made from it from now on are given.
|
|
154
|
-
* The sandboxes already made keep it. A key that is not there answers not_found.
|
|
155
|
-
*/
|
|
156
|
-
removeSshKey(keyId: string): Promise<void>;
|
|
157
|
-
private setSsh;
|
|
158
|
-
/** The sandboxes on it, each with whether it has the template as it is now, and its own addresses. */
|
|
159
|
-
sandboxes(): Promise<TemplateSandbox[]>;
|
|
160
|
-
/**
|
|
161
|
-
* Brings running sandboxes on it up to date with it now: the ones named, or all of them.
|
|
162
|
-
* Nothing is restarted. A stopped one takes it when it next starts. One whose server did
|
|
163
|
-
* not take the outbound rule is in failed, and is held to the rule it had.
|
|
164
|
-
*/
|
|
165
|
-
apply(sandboxIds?: string[]): Promise<TemplateApplied>;
|
|
166
|
-
}
|
|
167
|
-
/** Your templates. Every account has one named default. */
|
|
168
|
-
export declare class Templates {
|
|
169
|
-
private readonly http;
|
|
170
|
-
constructor(http: Http);
|
|
171
|
-
/** Every template you have, default first. */
|
|
172
|
-
list(): Promise<Template[]>;
|
|
173
|
-
get(id: string): Promise<Template>;
|
|
174
|
-
/** The template of this name, or null. */
|
|
175
|
-
find(name: string): Promise<Template | null>;
|
|
176
|
-
/** The account's default: the template a sandbox is on when none is chosen. */
|
|
177
|
-
default(): Promise<Template>;
|
|
178
|
-
/** Makes a template with nothing in it but the tags and metadata given, which every sandbox on it is shown with. */
|
|
179
|
-
create(name: string, labels?: {
|
|
180
|
-
tags?: string[];
|
|
181
|
-
metadata?: Record<string, string>;
|
|
182
|
-
}): Promise<Template>;
|
|
183
|
-
}
|
package/dist/template.js
DELETED
|
@@ -1,261 +0,0 @@
|
|
|
1
|
-
import { AgentalError } from "./errors.js";
|
|
2
|
-
import { tagSegment } from "./http.js";
|
|
3
|
-
/**
|
|
4
|
-
* Secrets: a template's, or a sandbox's own. Variables are in the environment of every
|
|
5
|
-
* command run in a sandbox, and files are written into its work folder before each one.
|
|
6
|
-
* A sandbox's own come on top of its template's: where both name the same variable or
|
|
7
|
-
* path, its own is used. Values are read one at a time. A variable kept out of the sandbox
|
|
8
|
-
* is in the environment as its stand-in, and its value is never given back.
|
|
9
|
-
*/
|
|
10
|
-
export class Secrets {
|
|
11
|
-
http;
|
|
12
|
-
path;
|
|
13
|
-
constructor(http, path) {
|
|
14
|
-
this.http = http;
|
|
15
|
-
this.path = path;
|
|
16
|
-
}
|
|
17
|
-
/** The names of the variables. hidden() says which of them are kept out of the sandbox. */
|
|
18
|
-
async variables() {
|
|
19
|
-
return (await this.listed()).names;
|
|
20
|
-
}
|
|
21
|
-
/** The names of the variables kept out of the sandbox. */
|
|
22
|
-
async hidden() {
|
|
23
|
-
return (await this.listed()).hidden;
|
|
24
|
-
}
|
|
25
|
-
/**
|
|
26
|
-
* One variable's value. A variable kept out of the sandbox has none to give, and is
|
|
27
|
-
* thrown as an AgentalError: variable() gives its hosts and its stand-in.
|
|
28
|
-
*/
|
|
29
|
-
async get(name) {
|
|
30
|
-
const found = await this.variable(name);
|
|
31
|
-
if (found.hidden) {
|
|
32
|
-
throw new AgentalError(`${name} is kept out of the sandbox, and its value is never given back. variable("${name}") gives its hosts and its stand-in.`);
|
|
33
|
-
}
|
|
34
|
-
return found.value;
|
|
35
|
-
}
|
|
36
|
-
/** One variable: a plain one with its value, or one kept out of the sandbox with its hosts and its stand-in. hidden says which. */
|
|
37
|
-
async variable(name) {
|
|
38
|
-
return (await this.http.json({ method: "GET", path: this.variablePath(name), replay: true })).body;
|
|
39
|
-
}
|
|
40
|
-
async set(name, value, options = {}) {
|
|
41
|
-
const body = options.hosts === undefined ? { value } : { value, hosts: options.hosts };
|
|
42
|
-
return (await this.http.json({ method: "PUT", path: this.variablePath(name), body, replay: true })).body;
|
|
43
|
-
}
|
|
44
|
-
/**
|
|
45
|
-
* Narrows the hosts a variable kept out of the sandbox is sent to, in place of the ones it
|
|
46
|
-
* had, without sending its value again. Its value and its stand-in stay as they are. Each
|
|
47
|
-
* host has to be one it is sent to now, or under one of its wildcards: a new one is refused
|
|
48
|
-
* with hosts_widened, and needs set() with the value. A plain variable is refused with
|
|
49
|
-
* not_hidden: set it with its value and hosts to keep it out.
|
|
50
|
-
*/
|
|
51
|
-
async setHosts(name, hosts) {
|
|
52
|
-
return (await this.http.json({ method: "PUT", path: `${this.variablePath(name)}/hosts`, body: { hosts }, replay: true })).body;
|
|
53
|
-
}
|
|
54
|
-
async delete(name) {
|
|
55
|
-
await this.http.send({ method: "DELETE", path: this.variablePath(name) });
|
|
56
|
-
}
|
|
57
|
-
/** The paths of the files, relative to the work folder. */
|
|
58
|
-
async files() {
|
|
59
|
-
return (await this.http.json({ method: "GET", path: `${this.path}/files`, replay: true })).body.paths;
|
|
60
|
-
}
|
|
61
|
-
/** What one file holds. */
|
|
62
|
-
async readFile(path) {
|
|
63
|
-
return (await this.http.json({ method: "GET", path: `${this.path}/files`, query: { path }, replay: true })).body.text;
|
|
64
|
-
}
|
|
65
|
-
/** Sets a file, and gives the path as it is kept, written one way. */
|
|
66
|
-
async writeFile(path, text) {
|
|
67
|
-
return (await this.http.json({ method: "PUT", path: `${this.path}/files`, body: { path, text }, replay: true })).body.path;
|
|
68
|
-
}
|
|
69
|
-
/** Stops writing a file. A copy already written to a sandbox's disk stays there. */
|
|
70
|
-
async deleteFile(path) {
|
|
71
|
-
await this.http.send({ method: "DELETE", path: `${this.path}/files`, query: { path } });
|
|
72
|
-
}
|
|
73
|
-
async listed() {
|
|
74
|
-
const { body } = await this.http.json({ method: "GET", path: `${this.path}/variables`, replay: true });
|
|
75
|
-
// An API from before variables could be kept out of the sandbox says nothing of them.
|
|
76
|
-
return { names: body.names, hidden: body.hidden ?? [] };
|
|
77
|
-
}
|
|
78
|
-
variablePath(name) {
|
|
79
|
-
return `${this.path}/variables/${encodeURIComponent(name)}`;
|
|
80
|
-
}
|
|
81
|
-
}
|
|
82
|
-
export class Template {
|
|
83
|
-
http;
|
|
84
|
-
secrets;
|
|
85
|
-
/** The template as it was last read. refresh() reads it again. */
|
|
86
|
-
info;
|
|
87
|
-
path;
|
|
88
|
-
constructor(http, info) {
|
|
89
|
-
this.http = http;
|
|
90
|
-
this.info = info;
|
|
91
|
-
this.path = `/v1/templates/${encodeURIComponent(info.id)}`;
|
|
92
|
-
this.secrets = new Secrets(http, `${this.path}/secrets`);
|
|
93
|
-
}
|
|
94
|
-
get id() {
|
|
95
|
-
return this.info.id;
|
|
96
|
-
}
|
|
97
|
-
get name() {
|
|
98
|
-
return this.info.name;
|
|
99
|
-
}
|
|
100
|
-
/** Whether it is the account's default, which a sandbox is on when none is chosen. */
|
|
101
|
-
get isDefault() {
|
|
102
|
-
return this.info.default;
|
|
103
|
-
}
|
|
104
|
-
async refresh() {
|
|
105
|
-
this.info = (await this.http.json({ method: "GET", path: this.path, replay: true })).body;
|
|
106
|
-
return this;
|
|
107
|
-
}
|
|
108
|
-
async rename(name) {
|
|
109
|
-
return await this.update({ name });
|
|
110
|
-
}
|
|
111
|
-
/** Its tags, which every sandbox on it is shown with too. */
|
|
112
|
-
get tags() {
|
|
113
|
-
return [...(this.info.tags ?? [])];
|
|
114
|
-
}
|
|
115
|
-
/** Its metadata, which every sandbox on it has too, under the sandbox's own value for a key. */
|
|
116
|
-
get metadata() {
|
|
117
|
-
return { ...this.info.metadata };
|
|
118
|
-
}
|
|
119
|
-
/**
|
|
120
|
-
* Changes its name, its tags or its metadata. tags are put in place of the ones it has,
|
|
121
|
-
* and metadata is merged in, null taking a key away. Every sandbox on it is shown the
|
|
122
|
-
* change at once.
|
|
123
|
-
*/
|
|
124
|
-
async update(changes) {
|
|
125
|
-
this.info = (await this.http.json({ method: "PATCH", path: this.path, body: changes, replay: true })).body;
|
|
126
|
-
return this;
|
|
127
|
-
}
|
|
128
|
-
/** Gives it a tag, and so every sandbox on it. One it has already is left as it is. */
|
|
129
|
-
async addTag(tag) {
|
|
130
|
-
this.info = (await this.http.json({ method: "PUT", path: `${this.path}/tags/${tagSegment(tag)}`, replay: true })).body;
|
|
131
|
-
return this;
|
|
132
|
-
}
|
|
133
|
-
/** Takes a tag away. One it does not have is nothing to take. */
|
|
134
|
-
async removeTag(tag) {
|
|
135
|
-
this.info = (await this.http.json({ method: "DELETE", path: `${this.path}/tags/${tagSegment(tag)}`, replay: true })).body;
|
|
136
|
-
return this;
|
|
137
|
-
}
|
|
138
|
-
/** Deletes it. One that sandboxes are on is refused: put them on another template first. */
|
|
139
|
-
async delete() {
|
|
140
|
-
await this.http.send({ method: "DELETE", path: this.path });
|
|
141
|
-
}
|
|
142
|
-
/** What a sandbox made from it starts as. */
|
|
143
|
-
async start() {
|
|
144
|
-
return (await this.http.json({ method: "GET", path: `${this.path}/start`, replay: true })).body;
|
|
145
|
-
}
|
|
146
|
-
/**
|
|
147
|
-
* Sets what a sandbox made from it starts as, from now on: its size, the snapshot it starts
|
|
148
|
-
* from, and how many seconds it runs after each start before it is stopped, 60 at the
|
|
149
|
-
* least. snapshotId left out or null is a new machine. ttlSeconds left out stays as it was,
|
|
150
|
-
* and null is the deployment's default. One over maxTtlSeconds of policy() is refused with
|
|
151
|
-
* ttl_too_long. Sandboxes made before keep their size, their disk
|
|
152
|
-
* and their time limit.
|
|
153
|
-
*/
|
|
154
|
-
async setStart(start) {
|
|
155
|
-
const set = (await this.http.json({ method: "PUT", path: `${this.path}/start`, body: start, replay: true })).body;
|
|
156
|
-
this.info = { ...this.info, start: set };
|
|
157
|
-
return set;
|
|
158
|
-
}
|
|
159
|
-
/** The repository it links to, for reference. Nothing is cloned. */
|
|
160
|
-
async repo() {
|
|
161
|
-
return (await this.http.json({ method: "GET", path: `${this.path}/repo`, replay: true })).body;
|
|
162
|
-
}
|
|
163
|
-
async setRepo(repo) {
|
|
164
|
-
return (await this.http.json({ method: "PUT", path: `${this.path}/repo`, body: repo, replay: true })).body;
|
|
165
|
-
}
|
|
166
|
-
async removeRepo() {
|
|
167
|
-
await this.http.send({ method: "DELETE", path: `${this.path}/repo`, replay: true });
|
|
168
|
-
}
|
|
169
|
-
/** What a sandbox on it may reach outside itself, before the addresses of its own. One that was never set is open. */
|
|
170
|
-
async network() {
|
|
171
|
-
return (await this.http.json({ method: "GET", path: `${this.path}/network`, replay: true })).body;
|
|
172
|
-
}
|
|
173
|
-
/**
|
|
174
|
-
* Sets what a sandbox on it may reach outside itself, in place of the rule it had:
|
|
175
|
-
* { outbound: "open" }, { outbound: "blocked" }, or { outbound: "allowlist", allow: [...] }
|
|
176
|
-
* with every address it lets out to. A sandbox is held to it with its own addresses on
|
|
177
|
-
* top. One made from it is held to it from its first boot, and one already on it takes it
|
|
178
|
-
* when it next starts, or now when apply() names it. Only where policy() says networkPolicy.
|
|
179
|
-
*/
|
|
180
|
-
async setNetwork(rule) {
|
|
181
|
-
const set = (await this.http.json({ method: "PUT", path: `${this.path}/network`, body: rule, replay: true })).body;
|
|
182
|
-
this.info = { ...this.info, network: set };
|
|
183
|
-
return set;
|
|
184
|
-
}
|
|
185
|
-
/** What a sandbox made from it is given for SSH as it is made: whether SSH is turned on, and the keys let in. */
|
|
186
|
-
async ssh() {
|
|
187
|
-
return (await this.http.json({ method: "GET", path: `${this.path}/ssh`, replay: true })).body;
|
|
188
|
-
}
|
|
189
|
-
/**
|
|
190
|
-
* Turns SSH on for every sandbox made from it from now on, as Sandbox.ssh.on() would as it
|
|
191
|
-
* is made. A sandbox already made is not changed, and no key is let in: addSshKey() does
|
|
192
|
-
* that. Only where policy() says ssh.
|
|
193
|
-
*/
|
|
194
|
-
async sshOn() {
|
|
195
|
-
return await this.setSsh("PUT");
|
|
196
|
-
}
|
|
197
|
-
/** A sandbox made from it from now on has SSH off as it is made. Sandboxes already made, and the keys, are left as they are. */
|
|
198
|
-
async sshOff() {
|
|
199
|
-
return await this.setSsh("DELETE");
|
|
200
|
-
}
|
|
201
|
-
/** Lets a public key, one line as in an authorized keys file, in as root to every sandbox made from it from now on. Sandboxes already made are not changed. */
|
|
202
|
-
async addSshKey(publicKey) {
|
|
203
|
-
return (await this.http.json({ method: "POST", path: `${this.path}/ssh/keys`, body: { publicKey }, replay: true })).body;
|
|
204
|
-
}
|
|
205
|
-
/**
|
|
206
|
-
* Takes a key, by its id, out of what the sandboxes made from it from now on are given.
|
|
207
|
-
* The sandboxes already made keep it. A key that is not there answers not_found.
|
|
208
|
-
*/
|
|
209
|
-
async removeSshKey(keyId) {
|
|
210
|
-
await this.http.send({ method: "DELETE", path: `${this.path}/ssh/keys/${encodeURIComponent(keyId)}`, replay: true });
|
|
211
|
-
}
|
|
212
|
-
async setSsh(method) {
|
|
213
|
-
const set = (await this.http.json({ method, path: `${this.path}/ssh`, replay: true })).body;
|
|
214
|
-
this.info = { ...this.info, ssh: set };
|
|
215
|
-
return set;
|
|
216
|
-
}
|
|
217
|
-
/** The sandboxes on it, each with whether it has the template as it is now, and its own addresses. */
|
|
218
|
-
async sandboxes() {
|
|
219
|
-
return (await this.http.json({ method: "GET", path: `${this.path}/sandboxes`, replay: true })).body.sandboxes;
|
|
220
|
-
}
|
|
221
|
-
/**
|
|
222
|
-
* Brings running sandboxes on it up to date with it now: the ones named, or all of them.
|
|
223
|
-
* Nothing is restarted. A stopped one takes it when it next starts. One whose server did
|
|
224
|
-
* not take the outbound rule is in failed, and is held to the rule it had.
|
|
225
|
-
*/
|
|
226
|
-
async apply(sandboxIds) {
|
|
227
|
-
const body = sandboxIds === undefined ? {} : { sandboxIds };
|
|
228
|
-
return (await this.http.json({ method: "POST", path: `${this.path}/apply`, body, replay: true })).body;
|
|
229
|
-
}
|
|
230
|
-
}
|
|
231
|
-
/** Your templates. Every account has one named default. */
|
|
232
|
-
export class Templates {
|
|
233
|
-
http;
|
|
234
|
-
constructor(http) {
|
|
235
|
-
this.http = http;
|
|
236
|
-
}
|
|
237
|
-
/** Every template you have, default first. */
|
|
238
|
-
async list() {
|
|
239
|
-
const { body } = await this.http.json({ method: "GET", path: "/v1/templates", replay: true });
|
|
240
|
-
return body.templates.map((info) => new Template(this.http, info));
|
|
241
|
-
}
|
|
242
|
-
async get(id) {
|
|
243
|
-
return new Template(this.http, (await this.http.json({ method: "GET", path: `/v1/templates/${encodeURIComponent(id)}`, replay: true })).body);
|
|
244
|
-
}
|
|
245
|
-
/** The template of this name, or null. */
|
|
246
|
-
async find(name) {
|
|
247
|
-
return (await this.list()).find((template) => template.name === name) ?? null;
|
|
248
|
-
}
|
|
249
|
-
/** The account's default: the template a sandbox is on when none is chosen. */
|
|
250
|
-
async default() {
|
|
251
|
-
const found = (await this.list()).find((template) => template.isDefault);
|
|
252
|
-
if (!found) {
|
|
253
|
-
throw new Error("The API listed no default template.");
|
|
254
|
-
}
|
|
255
|
-
return found;
|
|
256
|
-
}
|
|
257
|
-
/** Makes a template with nothing in it but the tags and metadata given, which every sandbox on it is shown with. */
|
|
258
|
-
async create(name, labels = {}) {
|
|
259
|
-
return new Template(this.http, (await this.http.json({ method: "POST", path: "/v1/templates", body: { name, ...labels } })).body);
|
|
260
|
-
}
|
|
261
|
-
}
|
package/dist/types.d.ts
DELETED
|
@@ -1,198 +0,0 @@
|
|
|
1
|
-
import type { components, operations } from "./openapi.js";
|
|
2
|
-
type Schemas = components["schemas"];
|
|
3
|
-
/** A sandbox as the API reports it. */
|
|
4
|
-
export type SandboxInfo = Schemas["Sandbox"];
|
|
5
|
-
export type SandboxStatus = SandboxInfo["status"];
|
|
6
|
-
/**
|
|
7
|
-
* When a running sandbox is to be stopped, how many seconds that is from now, and what
|
|
8
|
-
* decided it: ttl for its last start and ttlSeconds, account for a move by one of its
|
|
9
|
-
* account's keys or the console, sandbox for a move by the sandbox itself.
|
|
10
|
-
*/
|
|
11
|
-
export type SandboxAutoStop = Schemas["SandboxAutoStop"];
|
|
12
|
-
/**
|
|
13
|
-
* Where to move the stop of a sandbox's run under way: to a time, which may be a Date, or a
|
|
14
|
-
* number of seconds from now, 60 at the least. One of them, never both.
|
|
15
|
-
*/
|
|
16
|
-
export type SetAutoStop = {
|
|
17
|
-
at: string | Date;
|
|
18
|
-
inSeconds?: never;
|
|
19
|
-
} | {
|
|
20
|
-
inSeconds: number;
|
|
21
|
-
at?: never;
|
|
22
|
-
};
|
|
23
|
-
/** What a sandbox may reach outside itself: everything, nothing, or only the addresses in allow. Its template's rule with its own addresses on top. */
|
|
24
|
-
export type SandboxNetwork = Schemas["SandboxNetwork"];
|
|
25
|
-
/**
|
|
26
|
-
* What a sandbox may reach outside itself, and what that comes from: its template's rule as
|
|
27
|
-
* the sandbox has it, and its own addresses on top.
|
|
28
|
-
*/
|
|
29
|
-
export type SandboxNetworkDetail = Schemas["SandboxNetworkDetail"];
|
|
30
|
-
/** The addresses a sandbox may reach on top of its template's rule: IPv4 addresses and ranges. */
|
|
31
|
-
export type SandboxOwnNetwork = Schemas["SandboxOwnNetworkInput"];
|
|
32
|
-
/** What a sandbox on a template may reach outside itself, before its own addresses. */
|
|
33
|
-
export type TemplateNetwork = Schemas["TemplateNetwork"];
|
|
34
|
-
/** A rule to hold a template's sandboxes to: open, blocked, or allowlist with the IPv4 addresses and ranges in allow. */
|
|
35
|
-
export type NetworkRule = Schemas["TemplateNetworkInput"];
|
|
36
|
-
export type Size = SandboxInfo["size"];
|
|
37
|
-
/** What a command ended with. A command that failed is still an answer: read exitCode. */
|
|
38
|
-
export type ExecResult = Schemas["ExecResult"];
|
|
39
|
-
/** A command left running in the background, and its output so far. */
|
|
40
|
-
export type Command = Schemas["Command"];
|
|
41
|
-
/** A command a sandbox runs on a schedule, with its last run. */
|
|
42
|
-
export type Schedule = Schemas["Schedule"];
|
|
43
|
-
/** One run of a schedule: when it was due, how it ended, and whether it started and stopped its sandbox. */
|
|
44
|
-
export type ScheduleRun = Schemas["ScheduleRun"];
|
|
45
|
-
/** What a new schedule is: what it runs, and every or cron. */
|
|
46
|
-
export type CreateSchedule = Schemas["CreateSchedule"];
|
|
47
|
-
/** What to change in a schedule. What is left out is as it was. */
|
|
48
|
-
export type UpdateSchedule = Schemas["UpdateSchedule"];
|
|
49
|
-
export type Snapshot = Schemas["Snapshot"];
|
|
50
|
-
/** A port of a sandbox, and the address it is reached at. */
|
|
51
|
-
export type HostRoute = Schemas["HostRoute"];
|
|
52
|
-
/** Whether a sandbox has a desktop turned on, the size of its screen, and where it is watched. */
|
|
53
|
-
export type DesktopState = Schemas["DesktopState"];
|
|
54
|
-
/** A picture of a sandbox's screen in base64, with its media type, its size and the part of the screen it shows. */
|
|
55
|
-
export type DesktopScreenshot = Schemas["DesktopScreenshot"];
|
|
56
|
-
/** A link to a sandbox's desktop: to watch it or to use it, until it expires. */
|
|
57
|
-
export type DesktopLink = Schemas["DesktopLink"];
|
|
58
|
-
/** Whether a sandbox's browser is turned on to be driven from outside it, whether it has a window, and where to connect. */
|
|
59
|
-
export type BrowserState = Schemas["BrowserState"];
|
|
60
|
-
/** Whether SSH into a sandbox is on, and where to connect while it is: host, port, user, and the host key to pin. */
|
|
61
|
-
export type SshState = Schemas["SshState"];
|
|
62
|
-
/** A key that may log in to a sandbox as root: its id, fingerprint, type and comment. */
|
|
63
|
-
export type SshKey = Schemas["SshKey"];
|
|
64
|
-
/** Who a key or session belongs to: the account, its role, and whether it is closed. */
|
|
65
|
-
export type Me = operations["getMe"]["responses"][200]["content"]["application/json"];
|
|
66
|
-
export type Operation = Schemas["Operation"];
|
|
67
|
-
/** The sizes on offer and the room there is. */
|
|
68
|
-
export type Catalog = Schemas["Catalog"];
|
|
69
|
-
/** A region sandboxes can be made in: what it is called, where its servers are, and the sizes it has room for now. */
|
|
70
|
-
export type Region = Schemas["Region"];
|
|
71
|
-
export type Usage = Schemas["Usage"];
|
|
72
|
-
/**
|
|
73
|
-
* Where your account stands against its plan: what it runs against its running count, what
|
|
74
|
-
* its burst meter reads against the free burst, what it spent on burst fees this month
|
|
75
|
-
* against its budget, and what a start of each size would cost now.
|
|
76
|
-
*/
|
|
77
|
-
export type Burst = Omit<Schemas["Burst"], "quote"> & {
|
|
78
|
-
/** With burst({ size }), what starting that many of that size now would cost. Null without. */
|
|
79
|
-
quote: BurstQuote | null;
|
|
80
|
-
};
|
|
81
|
-
/** What starting so many sandboxes of one size now would cost in burst fees, and when it would cost nothing. */
|
|
82
|
-
export type BurstQuote = Schemas["BurstQuote"];
|
|
83
|
-
/** What a start costs when an account starts sandboxes faster than its plan's free burst, and the default monthly budget. */
|
|
84
|
-
export type BurstFee = Schemas["Prices"]["burstFee"];
|
|
85
|
-
/**
|
|
86
|
-
* A monthly plan: its price, the credits it includes, its running count, its free burst and its sizes.
|
|
87
|
-
* The API still sends sandboxesAtOnce and burst, the shape tiers had; they are not read here.
|
|
88
|
-
*/
|
|
89
|
-
export type Plan = Omit<Schemas["Prices"]["tiers"][number], "sandboxesAtOnce" | "burst">;
|
|
90
|
-
export type SandboxUsage = Schemas["SandboxUsage"];
|
|
91
|
-
/** What a sandbox read at one moment: its CPU, memory, disk and network. A figure its server did not have then is null. */
|
|
92
|
-
export type MetricsReading = Schemas["MetricsReading"];
|
|
93
|
-
/** What one sandbox read between two moments, oldest first. */
|
|
94
|
-
export type SandboxMetrics = Schemas["SandboxMetrics"];
|
|
95
|
-
/** What each of your sandboxes read at one moment. A sandbox that was stopped then has a null reading. */
|
|
96
|
-
export type MetricsAtMoment = Schemas["MetricsAtMoment"];
|
|
97
|
-
/** How many of your sandboxes were running, step by step. */
|
|
98
|
-
export type RunningOverTime = Schemas["RunningOverTime"];
|
|
99
|
-
/** Where your sandboxes' metrics and events are sent, the names of its headers, and how the last export went. */
|
|
100
|
-
export type Telemetry = Schemas["Telemetry"];
|
|
101
|
-
/** How long an account keeps its sandboxes' history, and what agental keeps besides. */
|
|
102
|
-
export type DataRetention = Schemas["DataRetention"];
|
|
103
|
-
export type AccountExport = Schemas["AccountExport"];
|
|
104
|
-
/** What your collector answered one empty export. */
|
|
105
|
-
export type TelemetryTest = Schemas["TelemetryTest"];
|
|
106
|
-
/** A repository's runs-on pool: how many sandboxes of each size it keeps, the template they are made on, and the ones it has. */
|
|
107
|
-
export type RunsOnRepository = Schemas["RunsOnRepository"];
|
|
108
|
-
/** Each repository's runs-on pool, and the size a pool keeps where none was set. */
|
|
109
|
-
export type RunsOnRepositories = Schemas["RunsOnRepositories"];
|
|
110
|
-
export type Policy = Schemas["Policy"];
|
|
111
|
-
/** What is sold: the hourly price of each size, the monthly plans in tiers, the top-ups and their bonus, storage and the free month. */
|
|
112
|
-
export type Prices = Omit<Schemas["Prices"], "tiers" | "volumeDiscount"> & {
|
|
113
|
-
tiers: Plan[];
|
|
114
|
-
};
|
|
115
|
-
/** Where the account stands: its plan, in its free month or not, what it has used of the month, what is left of its top-ups, and whether it may run a sandbox. */
|
|
116
|
-
export type Billing = Omit<Schemas["Billing"], "plan" | "discount" | "sandboxesAtOnce"> & {
|
|
117
|
-
plan: Omit<NonNullable<Schemas["Billing"]["plan"]>, "sandboxesAtOnce" | "burst"> | null;
|
|
118
|
-
};
|
|
119
|
-
/** Where to send a person to pay, or null with changed true when a plan was moved at once. */
|
|
120
|
-
export type Checkout = Schemas["Checkout"];
|
|
121
|
-
/** The auto-reload as it is now: the top-up the saved card is charged for when the credits run out, or null while it is off. */
|
|
122
|
-
export type AutoReload = Schemas["AutoReload"];
|
|
123
|
-
/** Whether mail is on for a sandbox, and the domain its addresses end in. */
|
|
124
|
-
export type SandboxEmail = Schemas["SandboxEmail"];
|
|
125
|
-
/** A message as a list gives it: who it is from and for, what was made of its sender, and where a sent one has got to. */
|
|
126
|
-
export type EmailMessageSummary = Schemas["EmailMessageSummary"];
|
|
127
|
-
/** A message with its headers and what it says. What it says was written by whoever sent it, which may be anyone. */
|
|
128
|
-
export type EmailMessage = Schemas["EmailMessage"];
|
|
129
|
-
/** A page of messages, newest first, and the cursor for the page after it. */
|
|
130
|
-
export type EmailMessageList = Schemas["EmailMessageList"];
|
|
131
|
-
/** The account's mail: the handle its addresses carry, what its plan allows, and what it has had of that today. */
|
|
132
|
-
export type AccountEmail = Schemas["AccountEmail"];
|
|
133
|
-
/** A message for a sandbox to send. It goes to the address of the sandbox's own account and to no other. */
|
|
134
|
-
export type SendEmail = Schemas["SendEmail"];
|
|
135
|
-
/** A template as the API reports it: its start, its outbound rule, and the names of its variables and files, never their values. */
|
|
136
|
-
export type TemplateInfo = Schemas["Template"];
|
|
137
|
-
/**
|
|
138
|
-
* A variable of a template or of a sandbox: a plain one with its value, or one kept out of
|
|
139
|
-
* the sandbox with its hosts and its stand-in, never its value. hidden says which.
|
|
140
|
-
*/
|
|
141
|
-
export type SecretVariable = Schemas["SecretVariable"];
|
|
142
|
-
/** A variable whose commands read its value. */
|
|
143
|
-
export type PlainVariable = Schemas["PlainVariable"];
|
|
144
|
-
/**
|
|
145
|
-
* A variable kept out of the sandbox: its commands see standIn, and the proxy on the
|
|
146
|
-
* sandbox's server puts the value in place of the stand-in on HTTPS requests to its hosts.
|
|
147
|
-
* Its value is never given back, to its owner or anyone.
|
|
148
|
-
*/
|
|
149
|
-
export type HiddenVariable = Schemas["HiddenVariable"];
|
|
150
|
-
/** What a sandbox made from a template starts as: its size, a snapshot or a new machine, and how many seconds it runs after each start. */
|
|
151
|
-
export type TemplateStart = Schemas["TemplateStart"];
|
|
152
|
-
/** What a sandbox made from a template is given for SSH as it is made: whether SSH is turned on, and the keys let in. */
|
|
153
|
-
export type TemplateSsh = Schemas["TemplateSsh"];
|
|
154
|
-
export type TemplateRepo = Schemas["TemplateRepo"];
|
|
155
|
-
/** A sandbox on a template, whether it has the template as it is now, and the addresses of its own it may reach on top of the template's rule. */
|
|
156
|
-
export type TemplateSandbox = Schemas["TemplateSandboxes"]["sandboxes"][number];
|
|
157
|
-
/** The sandboxes an apply brought up to date, and those whose server did not take the template's rule, each with what went wrong. */
|
|
158
|
-
export type TemplateApplied = Schemas["TemplateApplied"];
|
|
159
|
-
/** Which template a sandbox is on, whether it is up to date with it, and the names of what it has from it. */
|
|
160
|
-
export type SandboxTemplate = Schemas["SandboxTemplate"];
|
|
161
|
-
/** An address your account's events are posted to, with its tries of the last 30 days. signingSecret is there only when it is made or given a new one. */
|
|
162
|
-
export type Webhook = operations["getWebhook"]["responses"][200]["content"]["application/json"];
|
|
163
|
-
/** One try at posting an event to a webhook: what was answered, which event it was a try of, and which try. */
|
|
164
|
-
export type WebhookDelivery = Webhook["deliveries"][number];
|
|
165
|
-
/** An API key as the API reports it: what it may do, which sandboxes and templates it reaches, until when, and from where. Never its secret. */
|
|
166
|
-
export type ApiKey = Schemas["ApiKey"];
|
|
167
|
-
/** A key just made, with its secret in secret. The secret is given this once, and only its hash is kept. */
|
|
168
|
-
export type CreatedApiKey = Schemas["CreatedApiKey"];
|
|
169
|
-
/** Something a key may be made to do, such as sandbox.read, exec or email.send, or "*" for everything, now and later. */
|
|
170
|
-
export type ApiKeyAction = ApiKey["actions"][number];
|
|
171
|
-
/** A named set of actions a key can be made with: read-only, full-sandbox, ci or admin. */
|
|
172
|
-
export type ApiKeyPreset = NonNullable<ApiKey["preset"]>;
|
|
173
|
-
/**
|
|
174
|
-
* What a key is made with: a name, a preset or the actions named, never both, and what
|
|
175
|
-
* limits it. expiresAt may be a Date.
|
|
176
|
-
*/
|
|
177
|
-
export type CreateApiKey = Omit<Schemas["CreateApiKey"], "preset" | "actions" | "expiresAt"> & {
|
|
178
|
-
expiresAt?: string | Date;
|
|
179
|
-
} & ({
|
|
180
|
-
preset: ApiKeyPreset;
|
|
181
|
-
actions?: never;
|
|
182
|
-
} | {
|
|
183
|
-
actions: ApiKeyAction[];
|
|
184
|
-
preset?: never;
|
|
185
|
-
});
|
|
186
|
-
/** An organization the key's person is in, with their role in it: their own, or a team. */
|
|
187
|
-
export type Organization = operations["listOrganizations"]["responses"][200]["content"]["application/json"]["organizations"][number];
|
|
188
|
-
/** A team, with the caller's role in it. */
|
|
189
|
-
export type Team = Schemas["Team"];
|
|
190
|
-
/** Someone in a team, with their role and when they were added. */
|
|
191
|
-
export type Member = Schemas["Member"];
|
|
192
|
-
/** An invitation to a team, open for seven days. */
|
|
193
|
-
export type Invite = Schemas["Invite"];
|
|
194
|
-
/** A role in a team. An owner is made from a member who is there; an invite asks for member or admin. */
|
|
195
|
-
export type TeamRole = Member["role"];
|
|
196
|
-
/** Running time of the sandboxes one key made, and what it comes to at the list price. */
|
|
197
|
-
export type ApiKeyUsage = Schemas["ApiKeyUsage"];
|
|
198
|
-
export {};
|
package/dist/types.js
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export {};
|
package/dist/version.d.ts
DELETED
package/dist/version.js
DELETED
package/dist/webhooks.d.ts
DELETED
|
@@ -1,6 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Whether a webhook came from agental. Pass the request's body exactly as it arrived,
|
|
3
|
-
* before any JSON parsing, the value of its X-Agental-Signature header, and the webhook's
|
|
4
|
-
* signing secret.
|
|
5
|
-
*/
|
|
6
|
-
export declare function verifyWebhook(body: string | Uint8Array, signature: string | null | undefined, secret: string): Promise<boolean>;
|