@nomac/sdk 1.1.0 → 1.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 CHANGED
@@ -82,7 +82,7 @@ const visitor = await signVisitor({ secret: process.env.NOMAC_EMBED_SECRET, sess
82
82
 
83
83
  ## Phones
84
84
 
85
- iPhone and iPad Simulators, ready in seconds. `nomac.phones.start({ device, label, reuse, limits })`, then `phone.waitUntilReady()`. `device` is `"iphone"` (iPhone 17 Pro, the default), `"ipad"` or `"iphone-pro-max"`, on iOS 27; a phone runs 8 hours at most.
85
+ iPhone and iPad Simulators, ready in seconds. `nomac.phones.start({ device, label, reuse, limits })`, then `phone.waitUntilReady()`. `device` is `"iphone"` (iPhone 17 Pro, the default), `"ipad"`, `"iphone-pro-max"` or `"iphone-duo"` (iPhone Duo: it boots closed, `device_use` with `fold` folds it), on iOS 27; a phone runs 8 hours at most.
86
86
 
87
87
  ```js
88
88
  const phone = await nomac.phones.start({ label: "user-42", reuse: true });
@@ -99,7 +99,7 @@ await phone.stop();
99
99
 
100
100
  `nomac.labels.get("user-42")` shows what NoMac keeps for a user: their running Macs and phones, and their drive (what it holds, its last save, whether its saves are charged, when it expires unused). `nomac.labels.delete("user-42")` deletes their drive and file copies and their phones' workspaces and saved states, when they delete their account with you. It answers `label_in_use` while a Mac or phone of theirs runs, and `label_busy` while their last drive still saves.
101
101
 
102
- Your account has 10 drives included; past them, each save of a user's drive costs 1¢ per GB of changed data, from your credit. A drive unused for 90 days is deleted.
102
+ Your account has 10 drives included; past them, each save of a user's drive costs 1¢ per GB of changed data, from your credit. A drive is deleted after 30 days without a session.
103
103
 
104
104
  ## Webhooks
105
105
 
@@ -109,12 +109,14 @@ const hook = await nomac.webhooks.create({ url: "https://platform.example/nomac"
109
109
 
110
110
  | Event | |
111
111
  | --- | --- |
112
+ | `mac.queued` | A start has to wait for its turn, and why (`reason`: `account_limit`, `drive` or `capacity`), until `queue_expires_at`. |
112
113
  | `mac.ready` | A Mac is running, with its label and whether its drive is on it. |
113
114
  | `mac.ending_soon` | It stops in about 10 minutes, and why: its time limit, its spend cap or the credit. |
114
115
  | `mac.ended` | It ended, with its cost, `reason` and whether its drive is still saving. |
115
116
  | `drive.saved` | A user's drive was saved, with what changed and its charge. |
116
- | `drive.deleted` | A user's drive was deleted: by you, or after 90 days unused. |
117
+ | `drive.deleted` | A user's drive was deleted: by you, or after 30 days without a session. |
117
118
  | `credit.low` | Your credit covers less than an hour of what runs now. |
119
+ | `phone.queued` | A phone has to wait for a free one, up to 5 minutes (`queue_expires_at`). |
118
120
  | `phone.ready`, `phone.ended` | A phone is ready, or ended, with its cost and `reason`. |
119
121
 
120
122
  Check every delivery before trusting it, with the raw body as received:
@@ -169,7 +169,8 @@ export interface FileLink {
169
169
  expires_at?: string;
170
170
  [field: string]: unknown;
171
171
  }
172
- export type PhoneDevice = "iphone" | "ipad" | "iphone-pro-max";
172
+ /** The phone a start asks for; "iphone-duo" is the iPhone Duo, which boots closed and folds with device_use. */
173
+ export type PhoneDevice = "iphone" | "ipad" | "iphone-pro-max" | "iphone-duo";
173
174
  export interface PhoneStartOptions {
174
175
  device?: PhoneDevice;
175
176
  /** Your user's id: letters, digits and . _ : @ -, up to 64. */
@@ -191,12 +192,6 @@ export interface PhoneSession {
191
192
  created_at?: string;
192
193
  cost?: Cost;
193
194
  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
195
  message?: string;
201
196
  [field: string]: unknown;
202
197
  }
@@ -300,7 +295,7 @@ export interface Credits {
300
295
  spendable_seconds: number;
301
296
  [field: string]: unknown;
302
297
  }
303
- export type WebhookEventType = "mac.ready" | "mac.ending_soon" | "mac.ended" | "drive.saved" | "drive.deleted" | "credit.low" | "phone.ready" | "phone.ended";
298
+ export type WebhookEventType = "mac.queued" | "mac.ready" | "mac.ending_soon" | "mac.ended" | "drive.saved" | "drive.deleted" | "credit.low" | "phone.queued" | "phone.ready" | "phone.ended";
304
299
  export interface Webhook {
305
300
  id: string;
306
301
  url: string;
@@ -324,6 +319,11 @@ export interface WebhookDelivery {
324
319
  }
325
320
  /** Why a Mac or phone ended. crashed: it or its host failed (failure_code says more). */
326
321
  export type EndReason = "stopped" | "idle" | "time_limit" | "spend_cap" | "credit" | "crashed" | "no_capacity" | "start_failed" | "queue_expired" | "drive_unavailable";
322
+ /**
323
+ * Why a start waits for its turn (mac.queued, phone.queued): the account's limit of Macs at once (with queue_seconds), its
324
+ * drive still on another Mac, or no Mac or phone free yet (a phone's only reason). Waiting is free.
325
+ */
326
+ export type QueueReason = "account_limit" | "drive" | "capacity";
327
327
  export interface WebhookSession {
328
328
  id: string;
329
329
  state: SessionState;
@@ -341,7 +341,18 @@ export interface WebhookSession {
341
341
  };
342
342
  device?: PhoneDevice;
343
343
  }
344
- export type WebhookEvent = {
344
+ export type WebhookEvent =
345
+ /** Only for a start that waits; mac.ready follows once it starts, or mac.ended if it has not by queue_expires_at. */
346
+ {
347
+ id: string;
348
+ type: "mac.queued";
349
+ created_at: string;
350
+ data: {
351
+ session: WebhookSession;
352
+ reason: QueueReason;
353
+ queue_expires_at: string;
354
+ };
355
+ } | {
345
356
  id: string;
346
357
  type: "mac.ready";
347
358
  created_at: string;
@@ -406,6 +417,17 @@ export type WebhookEvent = {
406
417
  covers_seconds: number;
407
418
  };
408
419
  };
420
+ }
421
+ /** Only for a phone asked for while none is free; phone.ready follows, or phone.ended if none frees up by queue_expires_at. */
422
+ | {
423
+ id: string;
424
+ type: "phone.queued";
425
+ created_at: string;
426
+ data: {
427
+ session: WebhookSession;
428
+ reason: "capacity";
429
+ queue_expires_at: string;
430
+ };
409
431
  } | {
410
432
  id: string;
411
433
  type: "phone.ready";
package/dist/types.d.ts CHANGED
@@ -169,7 +169,8 @@ export interface FileLink {
169
169
  expires_at?: string;
170
170
  [field: string]: unknown;
171
171
  }
172
- export type PhoneDevice = "iphone" | "ipad" | "iphone-pro-max";
172
+ /** The phone a start asks for; "iphone-duo" is the iPhone Duo, which boots closed and folds with device_use. */
173
+ export type PhoneDevice = "iphone" | "ipad" | "iphone-pro-max" | "iphone-duo";
173
174
  export interface PhoneStartOptions {
174
175
  device?: PhoneDevice;
175
176
  /** Your user's id: letters, digits and . _ : @ -, up to 64. */
@@ -191,12 +192,6 @@ export interface PhoneSession {
191
192
  created_at?: string;
192
193
  cost?: Cost;
193
194
  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
195
  message?: string;
201
196
  [field: string]: unknown;
202
197
  }
@@ -300,7 +295,7 @@ export interface Credits {
300
295
  spendable_seconds: number;
301
296
  [field: string]: unknown;
302
297
  }
303
- export type WebhookEventType = "mac.ready" | "mac.ending_soon" | "mac.ended" | "drive.saved" | "drive.deleted" | "credit.low" | "phone.ready" | "phone.ended";
298
+ export type WebhookEventType = "mac.queued" | "mac.ready" | "mac.ending_soon" | "mac.ended" | "drive.saved" | "drive.deleted" | "credit.low" | "phone.queued" | "phone.ready" | "phone.ended";
304
299
  export interface Webhook {
305
300
  id: string;
306
301
  url: string;
@@ -324,6 +319,11 @@ export interface WebhookDelivery {
324
319
  }
325
320
  /** Why a Mac or phone ended. crashed: it or its host failed (failure_code says more). */
326
321
  export type EndReason = "stopped" | "idle" | "time_limit" | "spend_cap" | "credit" | "crashed" | "no_capacity" | "start_failed" | "queue_expired" | "drive_unavailable";
322
+ /**
323
+ * Why a start waits for its turn (mac.queued, phone.queued): the account's limit of Macs at once (with queue_seconds), its
324
+ * drive still on another Mac, or no Mac or phone free yet (a phone's only reason). Waiting is free.
325
+ */
326
+ export type QueueReason = "account_limit" | "drive" | "capacity";
327
327
  export interface WebhookSession {
328
328
  id: string;
329
329
  state: SessionState;
@@ -341,7 +341,18 @@ export interface WebhookSession {
341
341
  };
342
342
  device?: PhoneDevice;
343
343
  }
344
- export type WebhookEvent = {
344
+ export type WebhookEvent =
345
+ /** Only for a start that waits; mac.ready follows once it starts, or mac.ended if it has not by queue_expires_at. */
346
+ {
347
+ id: string;
348
+ type: "mac.queued";
349
+ created_at: string;
350
+ data: {
351
+ session: WebhookSession;
352
+ reason: QueueReason;
353
+ queue_expires_at: string;
354
+ };
355
+ } | {
345
356
  id: string;
346
357
  type: "mac.ready";
347
358
  created_at: string;
@@ -406,6 +417,17 @@ export type WebhookEvent = {
406
417
  covers_seconds: number;
407
418
  };
408
419
  };
420
+ }
421
+ /** Only for a phone asked for while none is free; phone.ready follows, or phone.ended if none frees up by queue_expires_at. */
422
+ | {
423
+ id: string;
424
+ type: "phone.queued";
425
+ created_at: string;
426
+ data: {
427
+ session: WebhookSession;
428
+ reason: "capacity";
429
+ queue_expires_at: string;
430
+ };
409
431
  } | {
410
432
  id: string;
411
433
  type: "phone.ready";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nomac/sdk",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
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
5
  "license": "MIT",
6
6
  "homepage": "https://nomac.app/docs/sdks",