@nomac/sdk 0.0.0-stage → 1.1.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/LICENSE +21 -0
- package/README.md +143 -2
- package/dist/account.d.ts +42 -0
- package/dist/account.js +50 -0
- package/dist/cjs/account.d.ts +42 -0
- package/dist/cjs/account.js +56 -0
- package/dist/cjs/embed.d.ts +47 -0
- package/dist/cjs/embed.js +70 -0
- package/dist/cjs/errors.d.ts +11 -0
- package/dist/cjs/errors.js +22 -0
- package/dist/cjs/http.d.ts +48 -0
- package/dist/cjs/http.js +145 -0
- package/dist/cjs/index.d.ts +42 -0
- package/dist/cjs/index.js +71 -0
- package/dist/cjs/mac.d.ts +176 -0
- package/dist/cjs/mac.js +353 -0
- package/dist/cjs/package.json +1 -0
- package/dist/cjs/phone.d.ts +134 -0
- package/dist/cjs/phone.js +205 -0
- package/dist/cjs/types.d.ts +424 -0
- package/dist/cjs/types.js +3 -0
- package/dist/cjs/webhooks.d.ts +10 -0
- package/dist/cjs/webhooks.js +24 -0
- package/dist/embed.d.ts +47 -0
- package/dist/embed.js +64 -0
- package/dist/errors.d.ts +11 -0
- package/dist/errors.js +17 -0
- package/dist/http.d.ts +48 -0
- package/dist/http.js +136 -0
- package/dist/index.d.ts +42 -0
- package/dist/index.js +54 -0
- package/dist/mac.d.ts +176 -0
- package/dist/mac.js +346 -0
- package/dist/phone.d.ts +134 -0
- package/dist/phone.js +200 -0
- package/dist/types.d.ts +424 -0
- package/dist/types.js +2 -0
- package/dist/webhooks.d.ts +10 -0
- package/dist/webhooks.js +21 -0
- package/package.json +48 -4
package/dist/cjs/mac.js
ADDED
|
@@ -0,0 +1,353 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.MacFiles = exports.MacJobs = exports.Mac = exports.Macs = void 0;
|
|
4
|
+
const errors_ts_1 = require("./errors.js");
|
|
5
|
+
const embed_ts_1 = require("./embed.js");
|
|
6
|
+
const http_ts_1 = require("./http.js");
|
|
7
|
+
const SESSIONS = "/api/v1/mac/sessions";
|
|
8
|
+
const ENDED = new Set(["stopping", "stopped", "failed"]);
|
|
9
|
+
const FINISHED = new Set(["exited", "unknown"]);
|
|
10
|
+
// The longest a request waits for a command on NoMac's side; the SDK asks again until the command ends.
|
|
11
|
+
const WAIT_SECONDS = 40;
|
|
12
|
+
// What one file call carries (larger files go by a link).
|
|
13
|
+
const FILE_CALL_BYTES = 3 * 1024 * 1024;
|
|
14
|
+
const decoder = new TextDecoder();
|
|
15
|
+
/** The account's Macs: start one (for one of your users with a label), read one, list them. */
|
|
16
|
+
class Macs {
|
|
17
|
+
#http;
|
|
18
|
+
constructor(http) {
|
|
19
|
+
this.#http = http;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Starts a Mac and answers it at once (queued, then provisioning): mac.waitUntilReady() follows it, usually under a minute.
|
|
23
|
+
* With label, it is your user's Mac: their drive at ~/drive and none of the account's secrets; with reuse too, the user's
|
|
24
|
+
* running Mac is the answer (mac.reused). Pass the same idempotencyKey to retry a start.
|
|
25
|
+
*/
|
|
26
|
+
async start(options = {}, { idempotencyKey = (0, errors_ts_1.requestKey)("start") } = {}) {
|
|
27
|
+
const answer = await this.#http.request("POST", SESSIONS, { body: options, idempotencyKey });
|
|
28
|
+
return new Mac(this.#http, answer.session, Boolean(answer.reused));
|
|
29
|
+
}
|
|
30
|
+
/** A Mac by its id, read. */
|
|
31
|
+
async get(id) {
|
|
32
|
+
return new Mac(this.#http, { id }).refresh();
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* Your users' Macs, newest first: one user's (label) or all of them (labeled: true), live or ended, a page at a time
|
|
36
|
+
* (before: the last id of the page before; more says whether another follows). Without label or labeled, the newest
|
|
37
|
+
* 100 of the account's own Macs.
|
|
38
|
+
*/
|
|
39
|
+
async list(filter = {}) {
|
|
40
|
+
const query = new URLSearchParams();
|
|
41
|
+
if (filter.label)
|
|
42
|
+
query.set("label", filter.label);
|
|
43
|
+
if (filter.labeled)
|
|
44
|
+
query.set("labeled", "true");
|
|
45
|
+
if (filter.state)
|
|
46
|
+
query.set("state", filter.state);
|
|
47
|
+
if (filter.before)
|
|
48
|
+
query.set("before", filter.before);
|
|
49
|
+
if (filter.limit)
|
|
50
|
+
query.set("limit", String(filter.limit));
|
|
51
|
+
const answer = await this.#http.request("GET", `${SESSIONS}${query.size ? `?${query}` : ""}`);
|
|
52
|
+
return { macs: answer.sessions.map(session => new Mac(this.#http, session)), more: Boolean(answer.more) };
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
exports.Macs = Macs;
|
|
56
|
+
/** A Mac: its session (state, label, drive, cost, limits) and what can be done on it. */
|
|
57
|
+
class Mac {
|
|
58
|
+
#http;
|
|
59
|
+
id;
|
|
60
|
+
session;
|
|
61
|
+
/** Whether a start with reuse answered this running Mac instead of a new one. */
|
|
62
|
+
reused;
|
|
63
|
+
/** As of the last refresh(), run() or extend(): set in the Mac's last 15 minutes before a limit or the credit's end. */
|
|
64
|
+
stopNotice = null;
|
|
65
|
+
files;
|
|
66
|
+
jobs;
|
|
67
|
+
constructor(http, session, reused = false) {
|
|
68
|
+
this.#http = http;
|
|
69
|
+
this.id = session.id;
|
|
70
|
+
this.session = session;
|
|
71
|
+
this.reused = reused;
|
|
72
|
+
this.files = new MacFiles(http, this.#path());
|
|
73
|
+
this.jobs = new MacJobs(http, this.#path(), notice => { this.stopNotice = notice ?? this.stopNotice; });
|
|
74
|
+
}
|
|
75
|
+
get state() {
|
|
76
|
+
return this.session.state;
|
|
77
|
+
}
|
|
78
|
+
/** Your user's id, for a Mac started with a label. */
|
|
79
|
+
get label() {
|
|
80
|
+
return this.session.label;
|
|
81
|
+
}
|
|
82
|
+
#path(rest = "") {
|
|
83
|
+
return `${SESSIONS}/${encodeURIComponent(this.id)}${rest}`;
|
|
84
|
+
}
|
|
85
|
+
/** Reads the Mac again. */
|
|
86
|
+
async refresh() {
|
|
87
|
+
const answer = await this.#http.request("GET", this.#path());
|
|
88
|
+
this.session = answer.session;
|
|
89
|
+
this.stopNotice = answer.stop_notice ?? null;
|
|
90
|
+
return this;
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* Waits until the Mac is ready: usually under a minute. A start waiting in line (queue_seconds) is waited for until its line
|
|
94
|
+
* ends, whatever timeoutMs says, so a Mac that starts in its turn is never left running unwatched.
|
|
95
|
+
*/
|
|
96
|
+
async waitUntilReady({ timeoutMs = 20 * 60_000, intervalMs = 2_000 } = {}) {
|
|
97
|
+
const lineEnds = Date.parse(String(this.session.queue_expires_at ?? "")) + 10 * 60_000;
|
|
98
|
+
const by = Math.max(Date.now() + timeoutMs, Number.isFinite(lineEnds) ? lineEnds : 0);
|
|
99
|
+
for (;;) {
|
|
100
|
+
if (this.state === "ready")
|
|
101
|
+
return this;
|
|
102
|
+
if (ENDED.has(this.state))
|
|
103
|
+
throw new errors_ts_1.NoMacError("mac_ended", `The Mac ended before it was ready (${this.session.failure_code ?? this.state}).`, 0, this.session);
|
|
104
|
+
if (Date.now() >= by)
|
|
105
|
+
throw new errors_ts_1.NoMacError("timeout", `The Mac was not ready within ${Math.round(timeoutMs / 1000)} s (${this.state}).`, 0, this.session);
|
|
106
|
+
await (0, http_ts_1.sleep)(intervalMs);
|
|
107
|
+
await this.refresh();
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* Runs a command and waits for it to end: {exitCode, stdout, stderr}, with the whole output. A string runs in bash -lc
|
|
112
|
+
* (pipes, &&, globs); an array runs as it is. A command that ends with a non-zero code is answered, not thrown.
|
|
113
|
+
*/
|
|
114
|
+
async run(command, options = {}) {
|
|
115
|
+
// A quick command ends within the start's own wait, and its answer carries the output: no second read.
|
|
116
|
+
return this.jobs.wait(await this.jobs.start(command, options), { timeoutMs: options.timeoutMs });
|
|
117
|
+
}
|
|
118
|
+
/** A JPEG of the desktop (1440x900, image pixels are screen points) or of the booted Simulator, with what is on the screen. */
|
|
119
|
+
async screenshot({ target = "screen" } = {}) {
|
|
120
|
+
const { image_base64, ...rest } = await this.#http.request("POST", this.#path("/screenshot"), { body: { target }, timeoutMs: 120_000 });
|
|
121
|
+
return { ...rest, image: (0, http_ts_1.fromBase64)(String(image_base64 ?? "")) };
|
|
122
|
+
}
|
|
123
|
+
/** The keyboard and mouse, which macOS takes as a person's (also on the lock screen and in password dialogs). Not repeated by itself: a retry types again. */
|
|
124
|
+
async input(action) {
|
|
125
|
+
// keys is a list; one key or chord may be given as a string.
|
|
126
|
+
const body = action.action === "key" && typeof action.keys === "string" ? { ...action, keys: [action.keys] } : action;
|
|
127
|
+
// Typing 500 characters and the screenshot after can take the server close to two minutes.
|
|
128
|
+
return this.#http.request("POST", this.#path("/input"), { body, timeoutMs: 120_000 });
|
|
129
|
+
}
|
|
130
|
+
/** Starts a video of the screen (or of the Simulator), which stops by itself after maxSeconds (300 by default, 1,800 at most). */
|
|
131
|
+
async startRecording({ target, maxSeconds } = {}) {
|
|
132
|
+
return this.#http.request("POST", this.#path("/recording"), { body: { ...(target ? { target } : {}), ...(maxSeconds ? { max_seconds: maxSeconds } : {}) } });
|
|
133
|
+
}
|
|
134
|
+
/** Stops the recording and answers its MP4 as a download link ({recording, link}); safe to repeat. */
|
|
135
|
+
async stopRecording() {
|
|
136
|
+
return this.#http.request("DELETE", this.#path("/recording"), { timeoutMs: 300_000 });
|
|
137
|
+
}
|
|
138
|
+
/** The Mac's login password ({user, password, variable}), also $NOMAC_MAC_PASSWORD on the Mac; each read is audited. */
|
|
139
|
+
async password() {
|
|
140
|
+
return this.#http.request("GET", this.#path("/password"));
|
|
141
|
+
}
|
|
142
|
+
/**
|
|
143
|
+
* A link to the Mac's desktop for a person, no sign-in, in a browser or an iframe (add ?embed=1): watch only, or control
|
|
144
|
+
* (one controller at a time; the newest takes over). Your user's Mac only (started with a label). Lasts 2 hours by default,
|
|
145
|
+
* a day at most; DELETE .../token (revokeTokens) ends it. allowedOrigins keeps it to frames on your sites, and visitor to your
|
|
146
|
+
* user, signed by your server (signVisitor); the account's embed settings apply when they are left out.
|
|
147
|
+
*/
|
|
148
|
+
async viewLink(options = {}) {
|
|
149
|
+
return this.#http.request("POST", this.#path("/view"), { body: (0, embed_ts_1.viewBody)(options) });
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* A token for this Mac only, to hand your user or their agent: new NoMac({ token }).mac(id) reaches its commands, files,
|
|
153
|
+
* screen, input and view links, never another Mac, a start, a stop or the account. 2 hours by default, a day at most.
|
|
154
|
+
*/
|
|
155
|
+
async token({ minutes } = {}) {
|
|
156
|
+
// Your user's Mac only (started with a label): the account's own Macs carry its secrets (not_a_platform_mac).
|
|
157
|
+
return this.#http.request("POST", this.#path("/token"), { body: minutes ? { minutes } : {} });
|
|
158
|
+
}
|
|
159
|
+
/** Revokes every token and link of this Mac made so far; the Mac runs on, and new ones work. The account's key only. */
|
|
160
|
+
async revokeTokens() {
|
|
161
|
+
return this.#http.request("DELETE", this.#path("/token"));
|
|
162
|
+
}
|
|
163
|
+
/**
|
|
164
|
+
* Keeps the Mac running longer: its time limit goes up by minutes (60 by default; a Mac has no longest time), and its
|
|
165
|
+
* spend cap by what that time costs. The account's key only. Not sent again by itself: a repeat adds more time.
|
|
166
|
+
*/
|
|
167
|
+
async extend({ minutes } = {}) {
|
|
168
|
+
const answer = await this.#http.request("POST", this.#path("/extend"), { body: minutes ? { minutes } : {} });
|
|
169
|
+
this.session = answer.session;
|
|
170
|
+
this.stopNotice = answer.stop_notice ?? null;
|
|
171
|
+
return this;
|
|
172
|
+
}
|
|
173
|
+
/**
|
|
174
|
+
* Stops the Mac: it and every file outside ~/drive are deleted, and ~/drive is saved for the next Mac. The account's key
|
|
175
|
+
* only. confirm: stop it even while another API key is using it (the account's own Macs ask; a user's Mac never does).
|
|
176
|
+
*/
|
|
177
|
+
async stop({ confirm = false } = {}) {
|
|
178
|
+
const answer = await this.#http.request("DELETE", this.#path(confirm ? "?confirm=true" : ""));
|
|
179
|
+
this.session = answer.session;
|
|
180
|
+
return this;
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
exports.Mac = Mac;
|
|
184
|
+
/** Commands on a Mac: start one, read it, wait for its end, cancel it. mac.run() is start and wait in one. */
|
|
185
|
+
class MacJobs {
|
|
186
|
+
#http;
|
|
187
|
+
#base;
|
|
188
|
+
#notice;
|
|
189
|
+
constructor(http, base, notice) {
|
|
190
|
+
this.#http = http;
|
|
191
|
+
this.#base = base;
|
|
192
|
+
this.#notice = notice;
|
|
193
|
+
}
|
|
194
|
+
/** Starts a command (a string runs in bash -lc) and answers its job, maybe already ended. The same idempotencyKey never runs it twice. */
|
|
195
|
+
async start(command, { cwd, env, timeoutSeconds, idempotencyKey = (0, errors_ts_1.requestKey)("run") } = {}) {
|
|
196
|
+
const argv = typeof command === "string" ? ["/bin/bash", "-lc", command] : command;
|
|
197
|
+
if (!argv.length)
|
|
198
|
+
throw new errors_ts_1.NoMacError("invalid_request", "Give a command: a string, or argv with at least one item.");
|
|
199
|
+
const job = await this.#http.request("POST", `${this.#base}/jobs?wait=${WAIT_SECONDS}`, {
|
|
200
|
+
body: { argv, ...(cwd ? { cwd } : {}), ...(env ? { env } : {}), ...(timeoutSeconds ? { timeout_seconds: timeoutSeconds } : {}) }, idempotencyKey, timeoutMs: (WAIT_SECONDS + 50) * 1000
|
|
201
|
+
});
|
|
202
|
+
this.#notice(job.stop_notice);
|
|
203
|
+
return job;
|
|
204
|
+
}
|
|
205
|
+
/** A job as it is now; with waitSeconds (up to 50), waits that long for it to end first. */
|
|
206
|
+
async get(id, { waitSeconds } = {}) {
|
|
207
|
+
const job = await this.#http.request("GET", `${this.#base}/jobs/${encodeURIComponent(id)}${waitSeconds ? `?wait=${waitSeconds}` : ""}`, { timeoutMs: ((waitSeconds ?? 0) + 50) * 1000 });
|
|
208
|
+
this.#notice(job.stop_notice);
|
|
209
|
+
return job;
|
|
210
|
+
}
|
|
211
|
+
/**
|
|
212
|
+
* Waits for a job (its id, or the job start answered) to end and answers its whole output. Never run a command again for its
|
|
213
|
+
* output: wait for its job.
|
|
214
|
+
*/
|
|
215
|
+
async wait(job, { timeoutMs = 2 * 60 * 60_000 } = {}) {
|
|
216
|
+
const by = Date.now() + timeoutMs, id = typeof job === "string" ? job : job.id;
|
|
217
|
+
// Only a waiting read answers an ended job's output: each read waits, the first one too.
|
|
218
|
+
let current = typeof job === "string" ? await this.get(id, { waitSeconds: WAIT_SECONDS }) : job;
|
|
219
|
+
while (!FINISHED.has(current.state)) {
|
|
220
|
+
if (Date.now() >= by)
|
|
221
|
+
throw new errors_ts_1.NoMacError("timeout", `The command ${id} was still running; it keeps running on the Mac: mac.jobs.wait("${id}") later.`, 0, current);
|
|
222
|
+
current = await this.get(id, { waitSeconds: WAIT_SECONDS });
|
|
223
|
+
}
|
|
224
|
+
const ended = current;
|
|
225
|
+
const exitCode = typeof ended.exit_code === "number" ? ended.exit_code : null;
|
|
226
|
+
try {
|
|
227
|
+
const [stdout, stderr] = await Promise.all([this.#stream(ended, "stdout"), this.#stream(ended, "stderr")]);
|
|
228
|
+
return { exitCode, stdout: stdout.text, stderr: stderr.text, truncated: stdout.truncated || stderr.truncated, job: ended };
|
|
229
|
+
}
|
|
230
|
+
catch (error) {
|
|
231
|
+
// The command ended, but its output could not be read (old output removed: output_expired): its exit code still counts.
|
|
232
|
+
// A credential that no longer reaches the Mac is the caller's to know, not a missing output.
|
|
233
|
+
if (!(error instanceof errors_ts_1.NoMacError) || error.status === 401 || error.status === 403)
|
|
234
|
+
throw error;
|
|
235
|
+
return { exitCode, stdout: "", stderr: "", truncated: false, job: ended, outputError: error.code };
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
/** Stops a running command and what it started; a finished one is answered as it is. */
|
|
239
|
+
async cancel(id) {
|
|
240
|
+
return this.#http.request("POST", `${this.#base}/jobs/${encodeURIComponent(id)}/cancel`);
|
|
241
|
+
}
|
|
242
|
+
/** A stream of an ended job, whole: what its answer carries, then the rest read from the Mac, and past 8 MiB its kept tail. */
|
|
243
|
+
async #stream(job, stream) {
|
|
244
|
+
if (typeof job[stream] === "string" && !job[`${stream}_more`]) {
|
|
245
|
+
const tail = job[`${stream}_tail`];
|
|
246
|
+
return { text: `${job[stream]}${typeof tail === "string" ? tail : ""}`, truncated: Boolean(job[`${stream}_truncated`]) };
|
|
247
|
+
}
|
|
248
|
+
const parts = [];
|
|
249
|
+
let truncated = false;
|
|
250
|
+
for (let cursor = 0, reads = 0; reads < 1000; reads++) {
|
|
251
|
+
const part = await this.#http.request("GET", `${this.#base}/jobs/${encodeURIComponent(job.id)}/output?stream=${stream}&cursor=${cursor}`);
|
|
252
|
+
parts.push((0, http_ts_1.fromBase64)(String(part.data_base64 ?? "")));
|
|
253
|
+
const next = Number.isSafeInteger(part.next_cursor) ? part.next_cursor : cursor;
|
|
254
|
+
if (part.eof || next === cursor) {
|
|
255
|
+
// Past the 8 MiB both streams share, a stream's last 64 KiB was kept apart: add what the kept start does not hold.
|
|
256
|
+
if (part.tail_base64 && Number(part.total_bytes) > next) {
|
|
257
|
+
const tail = (0, http_ts_1.fromBase64)(String(part.tail_base64)), start = Number(part.tail_offset);
|
|
258
|
+
parts.push(start > next ? tail : tail.subarray(next - start));
|
|
259
|
+
truncated = true;
|
|
260
|
+
}
|
|
261
|
+
break;
|
|
262
|
+
}
|
|
263
|
+
cursor = next;
|
|
264
|
+
}
|
|
265
|
+
const whole = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
|
|
266
|
+
let at = 0;
|
|
267
|
+
for (const part of parts) {
|
|
268
|
+
whole.set(part, at);
|
|
269
|
+
at += part.length;
|
|
270
|
+
}
|
|
271
|
+
return { text: decoder.decode(whole), truncated };
|
|
272
|
+
}
|
|
273
|
+
}
|
|
274
|
+
exports.MacJobs = MacJobs;
|
|
275
|
+
/** Files on a Mac: up to 3 MiB in a call, and any size up to 2 GiB through a link. Relative paths are in the workspace; ~ is home. */
|
|
276
|
+
class MacFiles {
|
|
277
|
+
#http;
|
|
278
|
+
#base;
|
|
279
|
+
constructor(http, base) {
|
|
280
|
+
this.#http = http;
|
|
281
|
+
this.#base = base;
|
|
282
|
+
}
|
|
283
|
+
/** Writes a file (folders made, the file replaced in one step, so safe to repeat). Larger than 3 MiB goes by an upload link. */
|
|
284
|
+
async write(path, content, { executable } = {}) {
|
|
285
|
+
// A large Blob goes to its link as it is, never read into memory here.
|
|
286
|
+
if (typeof Blob !== "undefined" && content instanceof Blob && content.size > FILE_CALL_BYTES)
|
|
287
|
+
return this.upload(path, content, { executable });
|
|
288
|
+
const bytes = await (0, http_ts_1.asBytes)(content);
|
|
289
|
+
if (bytes.byteLength > FILE_CALL_BYTES)
|
|
290
|
+
return this.upload(path, bytes, { executable });
|
|
291
|
+
return this.#http.request("POST", `${this.#base}/files`, { body: typeof content === "string" ? { path, content, ...(executable ? { executable } : {}) } : { path, content_base64: (0, http_ts_1.toBase64)(bytes), ...(executable ? { executable } : {}) } });
|
|
292
|
+
}
|
|
293
|
+
/** A file's bytes, any size up to 2 GiB (larger than 3 MiB comes by a download link). */
|
|
294
|
+
async readBytes(path) {
|
|
295
|
+
const file = await this.#http.request("GET", `${this.#base}/files?path=${encodeURIComponent(path)}&max_bytes=${FILE_CALL_BYTES}`);
|
|
296
|
+
if (!file.truncated)
|
|
297
|
+
return file.encoding === "base64" ? (0, http_ts_1.fromBase64)(String(file.content_base64 ?? "")) : new TextEncoder().encode(String(file.content ?? ""));
|
|
298
|
+
return this.download(path);
|
|
299
|
+
}
|
|
300
|
+
/** A text file, as UTF-8. */
|
|
301
|
+
async read(path) {
|
|
302
|
+
return decoder.decode(await this.readBytes(path));
|
|
303
|
+
}
|
|
304
|
+
/**
|
|
305
|
+
* A link that puts one file on the Mac at path, for a person (url: a page, no account) or a program (upload_url, then the
|
|
306
|
+
* link's own address to place it): extract unpacks a zip or tar into path. 60 minutes by default, a day at most.
|
|
307
|
+
*/
|
|
308
|
+
async uploadLink(path, options = {}) {
|
|
309
|
+
return this.#http.request("POST", `${this.#base}/links`, { body: { direction: "upload", path, ...(options.executable ? { executable: true } : {}), ...(options.extract ? { extract: options.extract } : {}), ...(options.minutes ? { expires_in_minutes: options.minutes } : {}) } });
|
|
310
|
+
}
|
|
311
|
+
/** A link to a file or a folder (as a zip) on the Mac, which keeps working after the Mac stops, until it expires. */
|
|
312
|
+
async downloadLink(path, options = {}) {
|
|
313
|
+
return this.#http.request("POST", `${this.#base}/links`, { body: { direction: "download", path, wait_seconds: options.waitSeconds ?? 30, ...(options.minutes ? { expires_in_minutes: options.minutes } : {}) } });
|
|
314
|
+
}
|
|
315
|
+
/** Puts bytes on the Mac at path through an upload link, and waits until the Mac has them. */
|
|
316
|
+
async upload(path, data, options = {}) {
|
|
317
|
+
const link = await this.uploadLink(path, options);
|
|
318
|
+
if (!link.upload_url)
|
|
319
|
+
throw new errors_ts_1.NoMacError("upload_unavailable", `The upload link is ${link.state}; ask for a new one.`, 0, link);
|
|
320
|
+
await this.#http.upload(link.upload_url, typeof Blob !== "undefined" && data instanceof Blob ? data : await (0, http_ts_1.asBytes)(data));
|
|
321
|
+
return this.#follow(link, ["placed"]);
|
|
322
|
+
}
|
|
323
|
+
/** A file's bytes (a folder's as a zip) from the Mac through a download link. */
|
|
324
|
+
async download(path) {
|
|
325
|
+
return this.#http.download(await this.#ready(path));
|
|
326
|
+
}
|
|
327
|
+
/** The same as a stream, for a file too large to hold in memory (up to 2 GiB): pipe it to a file or onward. */
|
|
328
|
+
async downloadStream(path) {
|
|
329
|
+
return this.#http.downloadStream(await this.#ready(path));
|
|
330
|
+
}
|
|
331
|
+
async #ready(path) {
|
|
332
|
+
const link = await this.#follow(await this.downloadLink(path), ["ready"]);
|
|
333
|
+
if (!link.download_url)
|
|
334
|
+
throw new errors_ts_1.NoMacError("download_unavailable", `The download link is ${link.state}.`, 0, link);
|
|
335
|
+
return String(link.download_url);
|
|
336
|
+
}
|
|
337
|
+
/** Reads a link (its own address, no credential needed) until it reaches one of states, or fails or expires. */
|
|
338
|
+
async #follow(link, states) {
|
|
339
|
+
const token = new URL(link.url).pathname.split("/").pop();
|
|
340
|
+
for (let current = link, rounds = 0; rounds < 200; rounds++) {
|
|
341
|
+
if (states.includes(current.state))
|
|
342
|
+
return current;
|
|
343
|
+
// A failed link says why (file_not_found, mac_stopped, ...) under error.
|
|
344
|
+
const why = current.error;
|
|
345
|
+
if (current.state === "failed" || current.state === "expired")
|
|
346
|
+
throw new errors_ts_1.NoMacError(why?.code ?? `link_${current.state}`, why?.message ?? String(current.message ?? `The link ${current.state}.`), 0, current);
|
|
347
|
+
// GET reads the link, moving an arrived upload onto the Mac, and waits for that move or a download's copy.
|
|
348
|
+
current = await this.#http.request("GET", `/api/v1/mac/links/${encodeURIComponent(String(token))}?wait=20`, { timeoutMs: 80_000 });
|
|
349
|
+
}
|
|
350
|
+
throw new errors_ts_1.NoMacError("timeout", "The file did not arrive in time; the link keeps going.", 0, link);
|
|
351
|
+
}
|
|
352
|
+
}
|
|
353
|
+
exports.MacFiles = MacFiles;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"type":"commonjs"}
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
import { type Transport } from "./http.ts";
|
|
2
|
+
import type { OperationOptions, PhoneLinks, PhoneRecording, PhoneSession, PhoneStartOptions, SessionToken, StopNotice, ToolName, ToolResult, ViewLink, ViewLinkOptions } from "./types.ts";
|
|
3
|
+
/** The account's phones (iPhone and iPad Simulators): start one (for one of your users with a label), read one, list them. */
|
|
4
|
+
export declare class Phones {
|
|
5
|
+
#private;
|
|
6
|
+
constructor(http: Transport);
|
|
7
|
+
/**
|
|
8
|
+
* Starts a phone and answers it at once, usually queued: phone.waitUntilReady() follows it (a phone from the pool is ready
|
|
9
|
+
* in seconds). With reuse and a label, the user's live phone is the answer (phone.reused). The same idempotencyKey retries.
|
|
10
|
+
*/
|
|
11
|
+
start(options?: PhoneStartOptions, { idempotencyKey }?: {
|
|
12
|
+
idempotencyKey?: string;
|
|
13
|
+
}): Promise<Phone>;
|
|
14
|
+
/** The account's phones, newest first; with label, one user's. */
|
|
15
|
+
list({ label }?: {
|
|
16
|
+
label?: string;
|
|
17
|
+
}): Promise<Phone[]>;
|
|
18
|
+
/** A phone by its id, read. */
|
|
19
|
+
get(id: string): Promise<Phone>;
|
|
20
|
+
}
|
|
21
|
+
/** A phone: its session (state, device, label, cost, deadlines) and links, and what can be done with it. */
|
|
22
|
+
export declare class Phone {
|
|
23
|
+
#private;
|
|
24
|
+
readonly id: string;
|
|
25
|
+
session: PhoneSession;
|
|
26
|
+
links: PhoneLinks | undefined;
|
|
27
|
+
/** Whether a start with reuse answered this live phone instead of a new one. */
|
|
28
|
+
readonly reused: boolean;
|
|
29
|
+
/** As of the last refresh(): set in the phone's last 15 minutes before a limit or the credit's end. */
|
|
30
|
+
stopNotice: StopNotice | null;
|
|
31
|
+
/** As of stop() or the last refresh(): the MP4 of a screen_record the phone's stop ended. */
|
|
32
|
+
recording: PhoneRecording | null;
|
|
33
|
+
constructor(http: Transport, session: PhoneSession, links?: PhoneLinks, reused?: boolean);
|
|
34
|
+
get state(): import("./types.ts").SessionState;
|
|
35
|
+
/** Reads the phone again. */
|
|
36
|
+
refresh(): Promise<this>;
|
|
37
|
+
/** Waits until the phone is ready (a phone from the pool takes seconds; a queued one up to 5 minutes). */
|
|
38
|
+
waitUntilReady({ timeoutMs, intervalMs }?: {
|
|
39
|
+
timeoutMs?: number;
|
|
40
|
+
intervalMs?: number;
|
|
41
|
+
}): Promise<this>;
|
|
42
|
+
/**
|
|
43
|
+
* Runs one of the phone's tools (ui_look, ui_act, app_run, tests_run, app_control, ...) and waits for its result: {text,
|
|
44
|
+
* content, isError, raw}. A long build that hands back a job is followed with job_status until it ends, unless waitForJobs is false.
|
|
45
|
+
*/
|
|
46
|
+
tool(name: ToolName | (string & {}), args?: Record<string, unknown>, { idempotencyKey, intervalMs, timeoutMs, waitForJobs }?: {
|
|
47
|
+
idempotencyKey?: string;
|
|
48
|
+
intervalMs?: number;
|
|
49
|
+
timeoutMs?: number;
|
|
50
|
+
waitForJobs?: boolean;
|
|
51
|
+
}): Promise<ToolResult>;
|
|
52
|
+
/** Stops a running tool call; a finished one is answered as it is. */
|
|
53
|
+
cancel(callId: string): Promise<Record<string, any>>;
|
|
54
|
+
/**
|
|
55
|
+
* A git repository into the phone's workspace: {url, ref?, token? | secret?}. A private repository's token is token itself
|
|
56
|
+
* (used for this fetch, kept nowhere) or secret, the account's secret holding it. Answers {root, commit}: root is the path
|
|
57
|
+
* app_run and tests_run take.
|
|
58
|
+
*/
|
|
59
|
+
fetchGit({ url, ref, token, secret }: {
|
|
60
|
+
url: string;
|
|
61
|
+
ref?: string;
|
|
62
|
+
token?: string;
|
|
63
|
+
secret?: string;
|
|
64
|
+
}, { idempotencyKey, timeoutMs }?: OperationOptions): Promise<{
|
|
65
|
+
state: "done";
|
|
66
|
+
root: string;
|
|
67
|
+
commit: string;
|
|
68
|
+
}>;
|
|
69
|
+
/** An archive (.tar.gz or .zip of a project, or of a Simulator .app) into the workspace under name, up to 2 GiB. Answers {root, app?}. */
|
|
70
|
+
uploadArchive(data: Uint8Array | ArrayBuffer | Blob, { name, idempotencyKey, timeoutMs }?: OperationOptions & {
|
|
71
|
+
name?: string;
|
|
72
|
+
}): Promise<{
|
|
73
|
+
state: "done";
|
|
74
|
+
root: string;
|
|
75
|
+
app?: string;
|
|
76
|
+
}>;
|
|
77
|
+
/**
|
|
78
|
+
* A link to the phone's live view for a person, no sign-in: watch only, or control: true. allowedOrigins keeps it to frames on
|
|
79
|
+
* your sites, and visitor to your user, signed by your server (signVisitor); the account's embed settings apply when left out.
|
|
80
|
+
*/
|
|
81
|
+
viewLink(options?: ViewLinkOptions): Promise<ViewLink>;
|
|
82
|
+
/** A token for this phone only, for your user or their agent: new NoMac({ token }).phone(id). 2 hours by default, a day at most. */
|
|
83
|
+
token({ minutes }?: {
|
|
84
|
+
minutes?: number;
|
|
85
|
+
}): Promise<SessionToken>;
|
|
86
|
+
/** Revokes every token and link of this phone made so far; the phone runs on. The account's key only. */
|
|
87
|
+
revokeTokens(): Promise<{
|
|
88
|
+
revoked_at: string;
|
|
89
|
+
}>;
|
|
90
|
+
/** The phone's replay: recording, saving after its stop, then ready with its video, its calls and a link. */
|
|
91
|
+
replay(): Promise<{
|
|
92
|
+
state: "recording" | "saving" | "ready" | "none";
|
|
93
|
+
link: string;
|
|
94
|
+
video_url?: string;
|
|
95
|
+
log_url?: string;
|
|
96
|
+
urls_expire_at?: string;
|
|
97
|
+
started_at?: string;
|
|
98
|
+
seconds?: number;
|
|
99
|
+
[field: string]: unknown;
|
|
100
|
+
}>;
|
|
101
|
+
/** Saves the phone's apps, their data, its keychain and permissions under name, for the account (and the label). */
|
|
102
|
+
saveState(name: string, { idempotencyKey, timeoutMs }?: OperationOptions): Promise<{
|
|
103
|
+
state: "done";
|
|
104
|
+
bytes?: number;
|
|
105
|
+
ms?: number;
|
|
106
|
+
device?: string;
|
|
107
|
+
[field: string]: unknown;
|
|
108
|
+
}>;
|
|
109
|
+
/** Puts a saved state back, onto a phone of the same model and iOS. */
|
|
110
|
+
restoreState(name: string, { idempotencyKey, timeoutMs }?: OperationOptions): Promise<{
|
|
111
|
+
state: "done";
|
|
112
|
+
bytes?: number;
|
|
113
|
+
ms?: number;
|
|
114
|
+
device?: string;
|
|
115
|
+
[field: string]: unknown;
|
|
116
|
+
}>;
|
|
117
|
+
/** The saved states, one per name (its newest save). */
|
|
118
|
+
listStates(): Promise<Array<{
|
|
119
|
+
name: string;
|
|
120
|
+
device: string | null;
|
|
121
|
+
bytes: number | null;
|
|
122
|
+
saved_at: string;
|
|
123
|
+
}>>;
|
|
124
|
+
deleteState(name: string): Promise<{
|
|
125
|
+
state: "done";
|
|
126
|
+
[field: string]: unknown;
|
|
127
|
+
}>;
|
|
128
|
+
/** More time (60 minutes by default, up to 8 hours in all), its spend cap with it; the account's key only. A repeat adds more. */
|
|
129
|
+
extend({ minutes }?: {
|
|
130
|
+
minutes?: number;
|
|
131
|
+
}): Promise<this>;
|
|
132
|
+
/** Stops the phone: its apps and data go, its workspace stays for the next phone, its replay is saved. */
|
|
133
|
+
stop(): Promise<this>;
|
|
134
|
+
}
|