@nomac/sdk 0.0.0-stage → 1.0.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.
@@ -0,0 +1,398 @@
1
+ /** The SDK's data, in the REST API's own field names (docs: https://nomac.app/docs/api). */
2
+ export type SessionState = "queued" | "provisioning" | "ready" | "stopping" | "stopped" | "failed";
3
+ /** What a session may cost and how long it may run. A Mac has no longest time; a phone runs 8 hours at most. */
4
+ export interface Limits {
5
+ /** The longest it runs, in seconds (7,200 by default). */
6
+ max_duration_seconds?: number;
7
+ /** Stopped after this long without a command, a call or a viewer, in seconds (600 by default, 60 to 3,600). */
8
+ idle_timeout_seconds?: number;
9
+ /** The most it may cost, in microdollars (USD x 1,000,000; "5000000", $5, by default). */
10
+ spend_cap_microunits?: string;
11
+ }
12
+ /** billable_seconds: the usage; billed_seconds: it as charged (whole minutes, at least one). */
13
+ export interface Cost {
14
+ currency: string;
15
+ accrued_microunits: string;
16
+ billable_seconds: number;
17
+ billed_seconds: number;
18
+ [field: string]: unknown;
19
+ }
20
+ /** When a Mac or phone stops, why, and what to do first. */
21
+ export interface StopNotice {
22
+ stops_at: string;
23
+ minutes_left: number;
24
+ reason: "time_limit" | "spend_cap" | "credit";
25
+ /** extend: extend() keeps it running; buy_credit: the account's owner adds credit (buy_url); save_state: a phone cannot be extended further. */
26
+ next_action?: "extend_mac" | "extend" | "save_state" | "buy_credit";
27
+ buy_url?: string;
28
+ message: string;
29
+ }
30
+ /** What a Mac starts with (the REST start's body): a label makes it a platform's user's Mac. */
31
+ export interface MacStartOptions {
32
+ /** Your user's id (letters, digits and . _ : @ -, up to 64): the Mac gets that user's drive and none of the account's secrets. */
33
+ label?: string;
34
+ /** With label: the user's starting or running Mac is the answer (mac.reused) instead of a second one. With access.drive: that drive's Mac. */
35
+ reuse?: boolean;
36
+ /** With label: the start ends (drive_unavailable, nothing charged) rather than run without the user's drive. */
37
+ require_drive?: boolean;
38
+ /** Wait in line, free, up to this long (300 to 3,600 s) when no Mac is free or the account runs its most at once. */
39
+ queue_seconds?: number;
40
+ limits?: Limits;
41
+ /** prompts "ask" keeps macOS's usual prompts; gatekeeper "on" | "off"; permissions; drive: "account", a name, or "none"; drive_from. */
42
+ access?: {
43
+ prompts?: "ask";
44
+ gatekeeper?: "on" | "off";
45
+ permissions?: Record<string, string[]> | "all";
46
+ drive?: string;
47
+ drive_from?: string;
48
+ [field: string]: unknown;
49
+ };
50
+ /** A second Mac beside the account's running one (an account that has bought credit). */
51
+ parallel?: boolean;
52
+ /** An SSH public key; leave it out for HTTPS only. */
53
+ public_key?: string;
54
+ }
55
+ export interface MacDrive {
56
+ id?: string;
57
+ name: string;
58
+ label?: string;
59
+ state?: string;
60
+ used_bytes?: number;
61
+ message?: string;
62
+ [field: string]: unknown;
63
+ }
64
+ export interface MacSession {
65
+ id: string;
66
+ state: SessionState;
67
+ label?: string;
68
+ limits?: Required<Limits>;
69
+ cost?: Cost;
70
+ ready_at?: string | null;
71
+ shutdown_at?: string | null;
72
+ cleanup_confirmed?: boolean;
73
+ failure_code?: string | null;
74
+ end_reason?: string | null;
75
+ drive?: MacDrive | null;
76
+ activity?: {
77
+ state: string;
78
+ idle_deadline_at: number | null;
79
+ hard_deadline_at: number | null;
80
+ };
81
+ started_from?: string | null;
82
+ last_command_at?: string | null;
83
+ created_at?: string;
84
+ [field: string]: unknown;
85
+ }
86
+ /** A command's end: its exit code and its whole output (or, past NoMac's 8 MiB, the start and the end with truncated set). */
87
+ export interface CommandResult {
88
+ exitCode: number | null;
89
+ stdout: string;
90
+ stderr: string;
91
+ /** More than 8 MiB of output: stdout and stderr hold the kept start and each stream's last 64 KiB. */
92
+ truncated: boolean;
93
+ /** The job as NoMac answered it: id, state, timings. */
94
+ job: Job;
95
+ /** Set when the command ended but its output could not be read (output_expired): exitCode still holds. */
96
+ outputError?: string;
97
+ }
98
+ export interface Job {
99
+ id: string;
100
+ state: "running" | "exited" | "unknown" | (string & {});
101
+ exit_code?: number | null;
102
+ [field: string]: unknown;
103
+ }
104
+ export interface RunOptions {
105
+ /** The folder to run in: relative to the workspace, ~/... or absolute. */
106
+ cwd?: string;
107
+ env?: Record<string, string>;
108
+ /** Stop the command after this many seconds (300 by default, 3,600 at most). */
109
+ timeoutSeconds?: number;
110
+ /** The same key makes a retry the same command (never run twice). */
111
+ idempotencyKey?: string;
112
+ }
113
+ export interface Screenshot {
114
+ /** The JPEG's bytes. */
115
+ image: Uint8Array;
116
+ mime_type: string;
117
+ width: number;
118
+ height: number;
119
+ target: "screen" | "simulator";
120
+ front_app?: string;
121
+ screen_locked?: boolean | null;
122
+ dialog?: string;
123
+ next_step?: string;
124
+ [field: string]: unknown;
125
+ }
126
+ export type InputAction =
127
+ /** text: up to 500 characters (longer: put it on the clipboard with run(), then key ["cmd+v"]). */
128
+ {
129
+ action: "type";
130
+ text: string;
131
+ screenshot?: boolean;
132
+ }
133
+ /** keys: one or more keys or chords, pressed in turn, like ["return"] or ["cmd+s"]. */
134
+ | {
135
+ action: "key";
136
+ keys: string[];
137
+ screenshot?: boolean;
138
+ } | {
139
+ action: "click";
140
+ x: number;
141
+ y: number;
142
+ button?: "left" | "right";
143
+ double?: boolean;
144
+ screenshot?: boolean;
145
+ } | {
146
+ action: "move";
147
+ x: number;
148
+ y: number;
149
+ screenshot?: boolean;
150
+ } | {
151
+ action: "scroll";
152
+ x: number;
153
+ y: number;
154
+ steps: number;
155
+ screenshot?: boolean;
156
+ } | {
157
+ action: "password" | "unlock" | "size";
158
+ screenshot?: boolean;
159
+ };
160
+ export interface FileLink {
161
+ url: string;
162
+ state: "waiting_for_upload" | "placing" | "placed" | "copying" | "ready" | "failed" | "expired" | (string & {});
163
+ error?: {
164
+ code: string;
165
+ message: string;
166
+ };
167
+ upload_url?: string;
168
+ download_url?: string;
169
+ expires_at?: string;
170
+ [field: string]: unknown;
171
+ }
172
+ export type PhoneDevice = "iphone" | "ipad" | "iphone-pro-max";
173
+ export interface PhoneStartOptions {
174
+ device?: PhoneDevice;
175
+ /** Your user's id: letters, digits and . _ : @ -, up to 64. */
176
+ label?: string;
177
+ /** With label: answer the live phone with that label instead of starting another. */
178
+ reuse?: boolean;
179
+ limits?: Limits;
180
+ }
181
+ export interface PhoneSession {
182
+ id: string;
183
+ state: SessionState;
184
+ device?: PhoneDevice;
185
+ label?: string | null;
186
+ ready_at?: string | null;
187
+ shutdown_at?: string | null;
188
+ failure_code?: string | null;
189
+ end_reason?: string | null;
190
+ queue_expires_at?: string;
191
+ created_at?: string;
192
+ cost?: Cost;
193
+ limits?: Required<Limits>;
194
+ /** While queued: how many phones were asked for before it, how many run at once, and how many are in use. */
195
+ queue?: {
196
+ ahead: number;
197
+ phones: number;
198
+ in_use: number;
199
+ };
200
+ message?: string;
201
+ [field: string]: unknown;
202
+ }
203
+ export interface PhoneLinks {
204
+ view?: string;
205
+ control?: string;
206
+ replay?: string;
207
+ [name: string]: string | undefined;
208
+ }
209
+ export type ToolName = "devices" | "device_use" | "app_run" | "ui_look" | "ui_act" | "app_control" | "app_logs" | "tests_run" | "job_status" | "job_cancel" | "screen_record";
210
+ export interface ToolResult {
211
+ /** The tool's text: what it did, what is on the screen, and what to do next. Files it names are links. */
212
+ text: string;
213
+ content: Array<{
214
+ type: "text";
215
+ text: string;
216
+ } | {
217
+ type: "image";
218
+ data: string;
219
+ mimeType: string;
220
+ } | {
221
+ type: string;
222
+ [field: string]: unknown;
223
+ }>;
224
+ isError: boolean;
225
+ /** "phone_restarted" when the phone restarted since the last call (apps and data kept). */
226
+ notices: string[];
227
+ stopNotice: StopNotice | null;
228
+ raw: Record<string, unknown>;
229
+ }
230
+ /** A screen_record still running when its phone stopped ends there: url is its MP4, about a minute after the stop, for 7 days. */
231
+ export interface PhoneRecording {
232
+ url: string;
233
+ started_at: string;
234
+ seconds: number;
235
+ message: string;
236
+ }
237
+ export interface OperationOptions {
238
+ idempotencyKey?: string;
239
+ /** How long to follow it before NoMacError "timeout" (30 minutes by default); the same key reads it later. */
240
+ timeoutMs?: number;
241
+ }
242
+ export interface ViewLink {
243
+ url: string;
244
+ mode: "watch" | "control";
245
+ expires_at: string;
246
+ }
247
+ export interface SessionToken {
248
+ token: string;
249
+ session_id: string;
250
+ expires_at: string;
251
+ }
252
+ /** What NoMac keeps for one of your users (a label): their running Macs and phones, and their drive. */
253
+ export interface LabelView {
254
+ label: string;
255
+ macs: {
256
+ running: string[];
257
+ drive: {
258
+ used_bytes: number;
259
+ saved_at: string | null;
260
+ saving: boolean;
261
+ charged: boolean;
262
+ expires_at: string;
263
+ } | null;
264
+ };
265
+ phones: {
266
+ running: string[];
267
+ [field: string]: unknown;
268
+ };
269
+ [field: string]: unknown;
270
+ }
271
+ export interface Credits {
272
+ currency: string;
273
+ spendable_microunits: string;
274
+ spendable_seconds: number;
275
+ [field: string]: unknown;
276
+ }
277
+ export type WebhookEventType = "mac.ready" | "mac.ending_soon" | "mac.ended" | "drive.saved" | "drive.deleted" | "credit.low" | "phone.ready" | "phone.ended";
278
+ export interface Webhook {
279
+ id: string;
280
+ url: string;
281
+ events: WebhookEventType[];
282
+ created_at: string;
283
+ /** Deliveries given up in the last 7 days (none answered 2xx in 12 tries). */
284
+ failing?: number;
285
+ }
286
+ export interface WebhookDelivery {
287
+ id: string;
288
+ event: WebhookEventType;
289
+ /** What it is about: a session's id, a drive's version, a credit episode. */
290
+ subject?: string;
291
+ session_id: string | null;
292
+ state: "delivered" | "retrying" | "gave_up";
293
+ attempts: number;
294
+ last_error: string | null;
295
+ created_at: string;
296
+ delivered_at: string | null;
297
+ next_attempt_at: string | null;
298
+ }
299
+ /** Why a Mac or phone ended. crashed: it or its host failed (failure_code says more). */
300
+ export type EndReason = "stopped" | "idle" | "time_limit" | "spend_cap" | "credit" | "crashed" | "no_capacity" | "start_failed" | "queue_expired" | "drive_unavailable";
301
+ export interface WebhookSession {
302
+ id: string;
303
+ state: SessionState;
304
+ label: string | null;
305
+ ready_at: string | null;
306
+ shutdown_at: string | null;
307
+ failure_code: string | null;
308
+ cost: Cost;
309
+ /** A Mac's drive: on mac.ready its state (mounted, preparing, unavailable, none), on mac.ended whether its save is still to come. */
310
+ drive?: {
311
+ name?: string;
312
+ label?: string;
313
+ state?: string;
314
+ saving?: boolean;
315
+ };
316
+ device?: PhoneDevice;
317
+ }
318
+ export type WebhookEvent = {
319
+ id: string;
320
+ type: "mac.ready";
321
+ created_at: string;
322
+ data: {
323
+ session: WebhookSession;
324
+ };
325
+ } | {
326
+ id: string;
327
+ type: "mac.ending_soon";
328
+ created_at: string;
329
+ data: {
330
+ session: {
331
+ id: string;
332
+ label: string | null;
333
+ };
334
+ stops_at: string;
335
+ seconds_left: number;
336
+ reason: "time_limit" | "spend_cap" | "credit";
337
+ };
338
+ } | {
339
+ id: string;
340
+ type: "mac.ended";
341
+ created_at: string;
342
+ data: {
343
+ session: WebhookSession;
344
+ reason: EndReason;
345
+ };
346
+ } | {
347
+ id: string;
348
+ type: "drive.saved";
349
+ created_at: string;
350
+ data: {
351
+ drive: {
352
+ label: string;
353
+ version: number;
354
+ head: boolean;
355
+ used_bytes: number;
356
+ changed_bytes: number;
357
+ charge_microunits: string;
358
+ };
359
+ session_id: string;
360
+ };
361
+ } | {
362
+ id: string;
363
+ type: "drive.deleted";
364
+ created_at: string;
365
+ data: {
366
+ drive: {
367
+ label: string;
368
+ reason: "deleted" | "expired";
369
+ };
370
+ };
371
+ } | {
372
+ id: string;
373
+ type: "credit.low";
374
+ created_at: string;
375
+ data: {
376
+ credit: {
377
+ spendable_microunits: string;
378
+ running_macs: number;
379
+ running_phones: number;
380
+ covers_seconds: number;
381
+ };
382
+ };
383
+ } | {
384
+ id: string;
385
+ type: "phone.ready";
386
+ created_at: string;
387
+ data: {
388
+ session: WebhookSession;
389
+ };
390
+ } | {
391
+ id: string;
392
+ type: "phone.ended";
393
+ created_at: string;
394
+ data: {
395
+ session: WebhookSession;
396
+ reason: EndReason;
397
+ };
398
+ };
package/dist/types.js ADDED
@@ -0,0 +1,2 @@
1
+ /** The SDK's data, in the REST API's own field names (docs: https://nomac.app/docs/api). */
2
+ export {};
@@ -0,0 +1,10 @@
1
+ import type { WebhookEvent } from "./types.ts";
2
+ /**
3
+ * Checks a webhook delivery and answers its event: body (the raw request body, as received), signature (the nomac-signature
4
+ * header), secret (the endpoint's whsec_... secret). Refused when the signature does not match or is older than toleranceSeconds
5
+ * (5 minutes). A delivery can come more than once: key on its id (the nomac-delivery header).
6
+ */
7
+ export declare function verifyWebhook(body: string | Uint8Array, signature: string | null | undefined, secret: string, { toleranceSeconds, now }?: {
8
+ toleranceSeconds?: number;
9
+ now?: number;
10
+ }): Promise<WebhookEvent>;
@@ -0,0 +1,21 @@
1
+ import { NoMacError } from "./errors.js";
2
+ const encoder = new TextEncoder();
3
+ /**
4
+ * Checks a webhook delivery and answers its event: body (the raw request body, as received), signature (the nomac-signature
5
+ * header), secret (the endpoint's whsec_... secret). Refused when the signature does not match or is older than toleranceSeconds
6
+ * (5 minutes). A delivery can come more than once: key on its id (the nomac-delivery header).
7
+ */
8
+ export async function verifyWebhook(body, signature, secret, { toleranceSeconds = 300, now = Date.now() } = {}) {
9
+ const text = typeof body === "string" ? body : new TextDecoder().decode(body);
10
+ const parts = Object.fromEntries(String(signature ?? "").split(",").map(part => part.trim().split("=", 2)));
11
+ const timestamp = Number(parts.t);
12
+ if (!Number.isInteger(timestamp) || !/^[a-f0-9]{64}$/.test(parts.v1 ?? ""))
13
+ throw new NoMacError("webhook_signature_invalid", "The nomac-signature header is missing or malformed.");
14
+ if (Math.abs(now / 1000 - timestamp) > toleranceSeconds)
15
+ throw new NoMacError("webhook_signature_expired", "The delivery's signature is too old; it may be a replay.");
16
+ const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
17
+ const mac = new Uint8Array(parts.v1.match(/../g).map(byte => parseInt(byte, 16)));
18
+ if (!(await crypto.subtle.verify("HMAC", key, mac, encoder.encode(`${timestamp}.${text}`))))
19
+ throw new NoMacError("webhook_signature_invalid", "The delivery's signature does not match this webhook's secret.");
20
+ return JSON.parse(text);
21
+ }
package/package.json CHANGED
@@ -1,6 +1,50 @@
1
1
  {
2
2
  "name": "@nomac/sdk",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.0",
4
+ "description": "NoMac from JavaScript and TypeScript: a cloud Mac or an iPhone Simulator for each of your users and agents, billed per minute. Commands, files, screen, live desktop and phone links, per-user drives and tokens, webhooks.",
5
+ "license": "MIT",
6
+ "homepage": "https://nomac.app/docs/sdks",
7
+ "keywords": [
8
+ "nomac",
9
+ "macos",
10
+ "mac",
11
+ "sandbox",
12
+ "ios",
13
+ "iphone",
14
+ "simulator",
15
+ "xcode",
16
+ "agents"
17
+ ],
18
+ "type": "module",
19
+ "main": "./dist/cjs/index.js",
20
+ "types": "./dist/index.d.ts",
21
+ "exports": {
22
+ ".": {
23
+ "import": {
24
+ "types": "./dist/index.d.ts",
25
+ "default": "./dist/index.js"
26
+ },
27
+ "require": {
28
+ "types": "./dist/cjs/index.d.ts",
29
+ "default": "./dist/cjs/index.js"
30
+ }
31
+ }
32
+ },
33
+ "files": [
34
+ "dist",
35
+ "README.md",
36
+ "LICENSE"
37
+ ],
38
+ "sideEffects": false,
39
+ "engines": {
40
+ "node": ">=20"
41
+ },
42
+ "scripts": {
43
+ "build": "rm -rf dist && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({ type: 'commonjs' }) + '\\\\n')\"",
44
+ "test": "npm run build && node --test test/*.test.js",
45
+ "prepack": "npm run build"
46
+ },
47
+ "devDependencies": {
48
+ "typescript": "5.9.3"
49
+ }
50
+ }