@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/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 NoMac
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,144 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @nomac/sdk
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[NoMac](https://nomac.app) from JavaScript and TypeScript: a cloud Mac, or an iPhone Simulator, for each of your users and agents, billed per minute. Run commands and builds on a Mac, read and write its files, see and use its screen, show its desktop to your user with no sign-in, keep each user's work on their own drive, and hear when their Mac is ready, ending or ended.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
npm install @nomac/sdk
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
No dependencies, typed, ESM and CommonJS. It runs wherever `fetch` and Web Crypto do: Node 20 and later, Bun, Deno and workers. Python: `pip install nomac`, the same calls.
|
|
10
|
+
|
|
11
|
+
```js
|
|
12
|
+
import { NoMac } from "@nomac/sdk";
|
|
13
|
+
|
|
14
|
+
const nomac = new NoMac(); // NOMAC_API_KEY from the environment
|
|
15
|
+
|
|
16
|
+
// A Mac for one of your users: their drive at ~/drive, none of your account's secrets.
|
|
17
|
+
const mac = await nomac.macs.start({ label: "user-42", reuse: true });
|
|
18
|
+
await mac.waitUntilReady();
|
|
19
|
+
|
|
20
|
+
const { exitCode, stdout } = await mac.run("git clone https://github.com/acme/app ~/drive/app && cd ~/drive/app && xcodebuild -list");
|
|
21
|
+
await mac.files.write("~/drive/app/.env", "API_URL=https://staging.example\n");
|
|
22
|
+
|
|
23
|
+
const { url } = await mac.viewLink({ control: true }); // the Mac's desktop for your user, no NoMac sign-in
|
|
24
|
+
const { token } = await mac.token(); // this Mac only, for your user's own agent
|
|
25
|
+
|
|
26
|
+
await mac.stop(); // ~/drive is saved for the user's next Mac
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
A Mac and a phone are billed per minute from the account's prepaid credit, with a one-minute minimum, at the hourly price each answer states ([pricing](https://nomac.app/docs/pricing)). Waiting in line is free.
|
|
30
|
+
|
|
31
|
+
## Macs
|
|
32
|
+
|
|
33
|
+
`nomac.macs.start(options)` starts a Mac and answers it at once (`queued`, then `provisioning`); `mac.waitUntilReady()` follows it, usually under a minute. The options are the REST start's own fields:
|
|
34
|
+
|
|
35
|
+
| Option | |
|
|
36
|
+
| --- | --- |
|
|
37
|
+
| `label` | Your user's id: letters, digits and `. _ : @ -`, up to 64, never an email. The Mac gets that user's drive at `~/drive` and none of your account's secrets, signing or drives. |
|
|
38
|
+
| `reuse` | With `label`: the user's starting or running Mac is the answer (`mac.reused`) instead of a second one. |
|
|
39
|
+
| `require_drive` | With `label`: the start ends (`drive_unavailable`, nothing charged) rather than run without the user's drive. |
|
|
40
|
+
| `queue_seconds` | Wait in line, free, up to this long (300 to 3,600) when no Mac is free or the account runs its most at once. |
|
|
41
|
+
| `limits.max_duration_seconds` | The time limit, 7,200 by default. A Mac has no longest time: ask for days if your user needs them. |
|
|
42
|
+
| `limits.spend_cap_microunits` | The most the Mac may cost, in microdollars; `"5000000"` ($5) by default, about 5.5 hours. Raise it with a longer limit. |
|
|
43
|
+
| `limits.idle_timeout_seconds` | Stopped after this long without a command, an SSH connection or a person's input; 600 by default, 60 to 3,600. Watching does not count. |
|
|
44
|
+
| `access` | `drive` (a drive name, or `"none"`), `prompts: "ask"`, `gatekeeper`, `permissions`: as the [REST API](https://nomac.app/docs/api). |
|
|
45
|
+
|
|
46
|
+
Your users' Macs take a Mac only while NoMac keeps one spare for its own customers: at busy hours a start without `queue_seconds` answers `capacity_unavailable`. A user's second Mac at the same time starts with `access: { drive: "none" }`. A retry with the same `idempotencyKey` (the second argument) answers the same Mac, never a second one.
|
|
47
|
+
|
|
48
|
+
`nomac.macs.get(id)` reads a Mac; `nomac.macs.list({ label })` lists one user's Macs, `{ labeled: true }` all of them, newest first, a page at a time (`before`, `limit`, and `more`). `mac.session` has its state, label, drive, limits, cost and deadlines; `mac.refresh()` reads it again. `mac.extend({ minutes })` keeps it running longer (its spend cap rises by what that time costs), and `mac.stop()` deletes it with every file outside `~/drive`.
|
|
49
|
+
|
|
50
|
+
### Commands
|
|
51
|
+
|
|
52
|
+
`mac.run(command)` runs a command and waits for its end, with its whole output: `{ exitCode, stdout, stderr, truncated }`. A string runs in `bash -lc` (pipes, `&&`, globs), an array as it is. A non-zero exit is answered, not thrown. Options: `cwd`, `env`, `timeoutSeconds` (300 by default, 3,600 at most). Past 8 MiB of output, `truncated` is set and each stream keeps its start and its last 64 KiB; if the output can no longer be read at all, `outputError` says why and `exitCode` still holds.
|
|
53
|
+
|
|
54
|
+
For a command you follow yourself: `mac.jobs.start(command)` answers its job, `mac.jobs.get(id, { waitSeconds })` reads it, `mac.jobs.wait(id)` waits for its end and output, and `mac.jobs.cancel(id)` stops it. A start is sent with a request key, so a lost answer never runs a command twice: wait for its job instead of running it again.
|
|
55
|
+
|
|
56
|
+
### Files
|
|
57
|
+
|
|
58
|
+
`mac.files.write(path, content)` writes text, bytes or a `Blob`, folders made and the file replaced in one step; `mac.files.read(path)` reads text and `readBytes(path)` bytes. Relative paths are in the workspace and `~` is home. Up to 3 MiB goes in a call and larger files, up to 2 GiB, through a link, both handled for you; a large `Blob` is sent as it is, never read into memory. `mac.files.downloadStream(path)` is a `ReadableStream` for a file too large to hold. `mac.files.uploadLink(path)` and `downloadLink(path)` make links a person opens in a browser, no account: a download keeps working after the Mac stops.
|
|
59
|
+
|
|
60
|
+
### Screen, input and the desktop
|
|
61
|
+
|
|
62
|
+
`mac.screenshot()` is a JPEG of the 1440x900 desktop (`{ image, front_app, screen_locked, dialog }`), or of the booted Simulator with `{ target: "simulator" }`. `mac.input({ action: "click", x, y })` uses the real keyboard and mouse, which macOS takes as a person's: `type` (`text`), `key` (`keys: ["cmd+s"]`), `click`, `move`, `scroll`, `password` and `unlock`. It is never sent twice by itself: a retry would type again. `mac.startRecording()` and `stopRecording()` make a video. `mac.password()` is the Mac's login password, also `$NOMAC_MAC_PASSWORD` on the Mac.
|
|
63
|
+
|
|
64
|
+
`mac.viewLink({ control })` is a link to your user's Mac's desktop, with no NoMac sign-in, for a browser or an iframe on your site (add `?embed=1`). A watch link shows the screen; a control link takes keyboard and mouse, one controller at a time: the newest takes over and the one before watches. Two viewers per Mac at once, and watching never keeps the Mac running. Links last 2 hours by default, a day at most.
|
|
65
|
+
|
|
66
|
+
### Only on your site, only for your user
|
|
67
|
+
|
|
68
|
+
```js
|
|
69
|
+
import { signVisitor } from "@nomac/sdk";
|
|
70
|
+
|
|
71
|
+
const { secret } = await nomac.embed.newSecret(); // once; keep it on your server as NOMAC_EMBED_SECRET
|
|
72
|
+
const { url } = await mac.viewLink({ control: true, allowedOrigins: ["https://app.example.com"], visitor: user.id });
|
|
73
|
+
const visitor = await signVisitor({ secret: process.env.NOMAC_EMBED_SECRET, sessionId: mac.id, visitor: user.id });
|
|
74
|
+
// In your page: <iframe src={`${url}?embed=1#visitor=${visitor}`}>
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
`allowedOrigins` lets only those sites frame the link, and browsers open it nowhere else. `visitor` makes it open only with your server's signature for that user, so a copied link opens nothing, in a browser or not. A signature lasts 5 minutes by default (15 at most), so sign one each time your page loads; the page then keeps working until the link expires. `nomac.embed.set({ allowedOrigins, requireVisitor })` makes both the default for every link made over the API from then on, the links in each phone's answer and those a token makes among them. Phone links take the same options.
|
|
78
|
+
|
|
79
|
+
### Tokens for your users
|
|
80
|
+
|
|
81
|
+
`mac.token({ minutes })` is a token for that Mac only, to hand your user or their agent: `new NoMac({ token }).mac(id)` reaches its commands, files, screen, input and view links, never another Mac, a start, a stop, an extension or your account, and sees no price. It lasts 2 hours by default, a day at most, and stops when the Mac ends, when the API key that made it is revoked, or with `mac.revokeTokens()`, which ends every token and link of the Mac with the Mac running on.
|
|
82
|
+
|
|
83
|
+
## Phones
|
|
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.
|
|
86
|
+
|
|
87
|
+
```js
|
|
88
|
+
const phone = await nomac.phones.start({ label: "user-42", reuse: true });
|
|
89
|
+
await phone.waitUntilReady();
|
|
90
|
+
const { root } = await phone.fetchGit({ url: "https://github.com/acme/demo", ref: "main" });
|
|
91
|
+
console.log((await phone.tool("app_run", { path: root, scheme: "Demo" })).text);
|
|
92
|
+
await phone.tool("ui_act", { steps: ['tap "Sign In"'] });
|
|
93
|
+
await phone.stop();
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
`phone.tool(name, args)` runs [simulator-use](https://github.com/NoMac-app/simulator-use)'s tools: `app_run` (build, install, launch), `tests_run`, `ui_look` (the screen as text), `ui_act` (tap and type by label), `app_control`, `app_logs`, `screen_record`. Projects arrive with `phone.fetchGit()` or `phone.uploadArchive()`, and builds are incremental between a user's phones. `phone.viewLink({ control })` and `phone.token()` work as a Mac's; [`@nomac/phone`](https://www.npmjs.com/package/@nomac/phone) embeds a phone in your page. `phone.saveState(name)` and `restoreState(name)` keep a signed-in app for the user's next phone, and `phone.replay()` is a video of every phone.
|
|
97
|
+
|
|
98
|
+
## Your users
|
|
99
|
+
|
|
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
|
+
|
|
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.
|
|
103
|
+
|
|
104
|
+
## Webhooks
|
|
105
|
+
|
|
106
|
+
```js
|
|
107
|
+
const hook = await nomac.webhooks.create({ url: "https://platform.example/nomac" }); // every event; keep hook.secret
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
| Event | |
|
|
111
|
+
| --- | --- |
|
|
112
|
+
| `mac.ready` | A Mac is running, with its label and whether its drive is on it. |
|
|
113
|
+
| `mac.ending_soon` | It stops in about 10 minutes, and why: its time limit, its spend cap or the credit. |
|
|
114
|
+
| `mac.ended` | It ended, with its cost, `reason` and whether its drive is still saving. |
|
|
115
|
+
| `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
|
+
| `credit.low` | Your credit covers less than an hour of what runs now. |
|
|
118
|
+
| `phone.ready`, `phone.ended` | A phone is ready, or ended, with its cost and `reason`. |
|
|
119
|
+
|
|
120
|
+
Check every delivery before trusting it, with the raw body as received:
|
|
121
|
+
|
|
122
|
+
```js
|
|
123
|
+
import { verifyWebhook } from "@nomac/sdk";
|
|
124
|
+
|
|
125
|
+
app.post("/nomac", express.raw({ type: "application/json" }), async (req, res) => {
|
|
126
|
+
const event = await verifyWebhook(req.body, req.get("nomac-signature"), process.env.NOMAC_WEBHOOK_SECRET);
|
|
127
|
+
if (event.type === "mac.ended") await bill(event.data.session.label, event.data.session.cost.accrued_microunits);
|
|
128
|
+
res.sendStatus(204);
|
|
129
|
+
});
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
A delivery not answered 2xx within 5 seconds is sent again 1, 2, 4 and up to 60 minutes later, 12 times in all. It can come more than once: key on its `id`. `nomac.webhooks.list()`, `delete(id)` and `deliveries(id)` manage them; an account has up to 5.
|
|
133
|
+
|
|
134
|
+
## Errors
|
|
135
|
+
|
|
136
|
+
A refusal is a `NoMacError` with NoMac's `code` (for code to branch on), `message` (for a person) and HTTP `status`: `insufficient_credit` (402), `session_limit_reached`, `drive_in_use`, `capacity_unavailable` or `label_in_use` (409). A read, a stop and any request with a request key (a start, a command) are sent again when NoMac is busy for a moment, with the same key, so they are never done twice; when one still fails, its error's `requestKey` is the key to send it with again and read what it did. `nomac.credits()` is the account's spendable credit and the time it buys.
|
|
137
|
+
|
|
138
|
+
## The REST API
|
|
139
|
+
|
|
140
|
+
The SDK is a thin layer over [NoMac's REST API](https://nomac.app/docs/api) with `Authorization: Bearer <API key or token>`, and `nomac.request(method, path, { body, idempotencyKey })` calls it directly.
|
|
141
|
+
|
|
142
|
+
From `@nomac/simulator`: `new NoMacSimulator()` is `new NoMac()`, with the same `phones`, and webhooks and label deletion on the account-wide routes.
|
|
143
|
+
|
|
144
|
+
MIT licensed.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import type { Transport } from "./http.ts";
|
|
2
|
+
import type { Credits, LabelView, Webhook, WebhookDelivery, WebhookEventType } from "./types.ts";
|
|
3
|
+
/** Your users, by the label you start their Macs and phones with: what NoMac keeps for each, and deleting it. */
|
|
4
|
+
export declare class Labels {
|
|
5
|
+
#private;
|
|
6
|
+
constructor(http: Transport);
|
|
7
|
+
/** A user's running Macs and phones, and their drive: what it holds, its last save, whether its saves are charged, when it expires unused. */
|
|
8
|
+
get(label: string): Promise<LabelView>;
|
|
9
|
+
/**
|
|
10
|
+
* Deletes what NoMac keeps for a user when they delete their account with you: their drive and file copies, and their phones'
|
|
11
|
+
* workspaces and saved states. Refused while a Mac or phone of theirs runs (label_in_use), or while their last drive or
|
|
12
|
+
* their last phone's replay still saves (label_busy, details.retry_after_seconds). A repeat finds nothing left. The account's key only.
|
|
13
|
+
*/
|
|
14
|
+
delete(label: string): Promise<Record<string, any>>;
|
|
15
|
+
}
|
|
16
|
+
/** Webhooks: your users' Macs, drives and phones, and the account's credit, POSTed to your https endpoint, signed. */
|
|
17
|
+
export declare class Webhooks {
|
|
18
|
+
#private;
|
|
19
|
+
constructor(http: Transport);
|
|
20
|
+
/**
|
|
21
|
+
* An endpoint for events (every kind when events is left out). Its secret is in this answer only: verify each delivery with
|
|
22
|
+
* verifyWebhook. A delivery is retried 1, 2, 4 ... 60 minutes later, 12 times, until answered 2xx. Up to 5 an account.
|
|
23
|
+
*/
|
|
24
|
+
create({ url, events }: {
|
|
25
|
+
url: string;
|
|
26
|
+
events?: WebhookEventType[];
|
|
27
|
+
}): Promise<Webhook & {
|
|
28
|
+
secret: string;
|
|
29
|
+
}>;
|
|
30
|
+
list(): Promise<Webhook[]>;
|
|
31
|
+
/** Ends an endpoint: nothing more is sent to it, its undelivered events included. */
|
|
32
|
+
delete(id: string): Promise<{
|
|
33
|
+
id: string;
|
|
34
|
+
deleted: true;
|
|
35
|
+
}>;
|
|
36
|
+
/** An endpoint's deliveries, newest first, kept 30 days: delivered, retrying, or gave_up after 12 tries, with the last error. */
|
|
37
|
+
deliveries(id: string, { limit }?: {
|
|
38
|
+
limit?: number;
|
|
39
|
+
}): Promise<WebhookDelivery[]>;
|
|
40
|
+
}
|
|
41
|
+
/** The account's prepaid credit: what it can spend and the time that buys. */
|
|
42
|
+
export declare function credits(http: Transport): Promise<Credits>;
|
package/dist/account.js
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
const LABELS = "/api/v1/labels";
|
|
2
|
+
const WEBHOOKS = "/api/v1/webhooks";
|
|
3
|
+
/** Your users, by the label you start their Macs and phones with: what NoMac keeps for each, and deleting it. */
|
|
4
|
+
export class Labels {
|
|
5
|
+
#http;
|
|
6
|
+
constructor(http) {
|
|
7
|
+
this.#http = http;
|
|
8
|
+
}
|
|
9
|
+
/** A user's running Macs and phones, and their drive: what it holds, its last save, whether its saves are charged, when it expires unused. */
|
|
10
|
+
async get(label) {
|
|
11
|
+
return this.#http.request("GET", `${LABELS}/${encodeURIComponent(label)}`);
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Deletes what NoMac keeps for a user when they delete their account with you: their drive and file copies, and their phones'
|
|
15
|
+
* workspaces and saved states. Refused while a Mac or phone of theirs runs (label_in_use), or while their last drive or
|
|
16
|
+
* their last phone's replay still saves (label_busy, details.retry_after_seconds). A repeat finds nothing left. The account's key only.
|
|
17
|
+
*/
|
|
18
|
+
async delete(label) {
|
|
19
|
+
return this.#http.request("DELETE", `${LABELS}/${encodeURIComponent(label)}`);
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
/** Webhooks: your users' Macs, drives and phones, and the account's credit, POSTed to your https endpoint, signed. */
|
|
23
|
+
export class Webhooks {
|
|
24
|
+
#http;
|
|
25
|
+
constructor(http) {
|
|
26
|
+
this.#http = http;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* An endpoint for events (every kind when events is left out). Its secret is in this answer only: verify each delivery with
|
|
30
|
+
* verifyWebhook. A delivery is retried 1, 2, 4 ... 60 minutes later, 12 times, until answered 2xx. Up to 5 an account.
|
|
31
|
+
*/
|
|
32
|
+
async create({ url, events }) {
|
|
33
|
+
return this.#http.request("POST", WEBHOOKS, { body: { url, ...(events ? { events } : {}) } });
|
|
34
|
+
}
|
|
35
|
+
async list() {
|
|
36
|
+
return (await this.#http.request("GET", WEBHOOKS)).webhooks;
|
|
37
|
+
}
|
|
38
|
+
/** Ends an endpoint: nothing more is sent to it, its undelivered events included. */
|
|
39
|
+
async delete(id) {
|
|
40
|
+
return this.#http.request("DELETE", `${WEBHOOKS}/${encodeURIComponent(id)}`);
|
|
41
|
+
}
|
|
42
|
+
/** An endpoint's deliveries, newest first, kept 30 days: delivered, retrying, or gave_up after 12 tries, with the last error. */
|
|
43
|
+
async deliveries(id, { limit } = {}) {
|
|
44
|
+
return (await this.#http.request("GET", `${WEBHOOKS}/${encodeURIComponent(id)}/deliveries${limit ? `?limit=${limit}` : ""}`)).deliveries;
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
/** The account's prepaid credit: what it can spend and the time that buys. */
|
|
48
|
+
export async function credits(http) {
|
|
49
|
+
return (await http.request("GET", "/api/v1/mac/credits")).credits;
|
|
50
|
+
}
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import type { Transport } from "./http.ts";
|
|
2
|
+
import type { Credits, LabelView, Webhook, WebhookDelivery, WebhookEventType } from "./types.ts";
|
|
3
|
+
/** Your users, by the label you start their Macs and phones with: what NoMac keeps for each, and deleting it. */
|
|
4
|
+
export declare class Labels {
|
|
5
|
+
#private;
|
|
6
|
+
constructor(http: Transport);
|
|
7
|
+
/** A user's running Macs and phones, and their drive: what it holds, its last save, whether its saves are charged, when it expires unused. */
|
|
8
|
+
get(label: string): Promise<LabelView>;
|
|
9
|
+
/**
|
|
10
|
+
* Deletes what NoMac keeps for a user when they delete their account with you: their drive and file copies, and their phones'
|
|
11
|
+
* workspaces and saved states. Refused while a Mac or phone of theirs runs (label_in_use), or while their last drive or
|
|
12
|
+
* their last phone's replay still saves (label_busy, details.retry_after_seconds). A repeat finds nothing left. The account's key only.
|
|
13
|
+
*/
|
|
14
|
+
delete(label: string): Promise<Record<string, any>>;
|
|
15
|
+
}
|
|
16
|
+
/** Webhooks: your users' Macs, drives and phones, and the account's credit, POSTed to your https endpoint, signed. */
|
|
17
|
+
export declare class Webhooks {
|
|
18
|
+
#private;
|
|
19
|
+
constructor(http: Transport);
|
|
20
|
+
/**
|
|
21
|
+
* An endpoint for events (every kind when events is left out). Its secret is in this answer only: verify each delivery with
|
|
22
|
+
* verifyWebhook. A delivery is retried 1, 2, 4 ... 60 minutes later, 12 times, until answered 2xx. Up to 5 an account.
|
|
23
|
+
*/
|
|
24
|
+
create({ url, events }: {
|
|
25
|
+
url: string;
|
|
26
|
+
events?: WebhookEventType[];
|
|
27
|
+
}): Promise<Webhook & {
|
|
28
|
+
secret: string;
|
|
29
|
+
}>;
|
|
30
|
+
list(): Promise<Webhook[]>;
|
|
31
|
+
/** Ends an endpoint: nothing more is sent to it, its undelivered events included. */
|
|
32
|
+
delete(id: string): Promise<{
|
|
33
|
+
id: string;
|
|
34
|
+
deleted: true;
|
|
35
|
+
}>;
|
|
36
|
+
/** An endpoint's deliveries, newest first, kept 30 days: delivered, retrying, or gave_up after 12 tries, with the last error. */
|
|
37
|
+
deliveries(id: string, { limit }?: {
|
|
38
|
+
limit?: number;
|
|
39
|
+
}): Promise<WebhookDelivery[]>;
|
|
40
|
+
}
|
|
41
|
+
/** The account's prepaid credit: what it can spend and the time that buys. */
|
|
42
|
+
export declare function credits(http: Transport): Promise<Credits>;
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.Webhooks = exports.Labels = void 0;
|
|
4
|
+
exports.credits = credits;
|
|
5
|
+
const LABELS = "/api/v1/labels";
|
|
6
|
+
const WEBHOOKS = "/api/v1/webhooks";
|
|
7
|
+
/** Your users, by the label you start their Macs and phones with: what NoMac keeps for each, and deleting it. */
|
|
8
|
+
class Labels {
|
|
9
|
+
#http;
|
|
10
|
+
constructor(http) {
|
|
11
|
+
this.#http = http;
|
|
12
|
+
}
|
|
13
|
+
/** A user's running Macs and phones, and their drive: what it holds, its last save, whether its saves are charged, when it expires unused. */
|
|
14
|
+
async get(label) {
|
|
15
|
+
return this.#http.request("GET", `${LABELS}/${encodeURIComponent(label)}`);
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Deletes what NoMac keeps for a user when they delete their account with you: their drive and file copies, and their phones'
|
|
19
|
+
* workspaces and saved states. Refused while a Mac or phone of theirs runs (label_in_use), or while their last drive or
|
|
20
|
+
* their last phone's replay still saves (label_busy, details.retry_after_seconds). A repeat finds nothing left. The account's key only.
|
|
21
|
+
*/
|
|
22
|
+
async delete(label) {
|
|
23
|
+
return this.#http.request("DELETE", `${LABELS}/${encodeURIComponent(label)}`);
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
exports.Labels = Labels;
|
|
27
|
+
/** Webhooks: your users' Macs, drives and phones, and the account's credit, POSTed to your https endpoint, signed. */
|
|
28
|
+
class Webhooks {
|
|
29
|
+
#http;
|
|
30
|
+
constructor(http) {
|
|
31
|
+
this.#http = http;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* An endpoint for events (every kind when events is left out). Its secret is in this answer only: verify each delivery with
|
|
35
|
+
* verifyWebhook. A delivery is retried 1, 2, 4 ... 60 minutes later, 12 times, until answered 2xx. Up to 5 an account.
|
|
36
|
+
*/
|
|
37
|
+
async create({ url, events }) {
|
|
38
|
+
return this.#http.request("POST", WEBHOOKS, { body: { url, ...(events ? { events } : {}) } });
|
|
39
|
+
}
|
|
40
|
+
async list() {
|
|
41
|
+
return (await this.#http.request("GET", WEBHOOKS)).webhooks;
|
|
42
|
+
}
|
|
43
|
+
/** Ends an endpoint: nothing more is sent to it, its undelivered events included. */
|
|
44
|
+
async delete(id) {
|
|
45
|
+
return this.#http.request("DELETE", `${WEBHOOKS}/${encodeURIComponent(id)}`);
|
|
46
|
+
}
|
|
47
|
+
/** An endpoint's deliveries, newest first, kept 30 days: delivered, retrying, or gave_up after 12 tries, with the last error. */
|
|
48
|
+
async deliveries(id, { limit } = {}) {
|
|
49
|
+
return (await this.#http.request("GET", `${WEBHOOKS}/${encodeURIComponent(id)}/deliveries${limit ? `?limit=${limit}` : ""}`)).deliveries;
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
exports.Webhooks = Webhooks;
|
|
53
|
+
/** The account's prepaid credit: what it can spend and the time that buys. */
|
|
54
|
+
async function credits(http) {
|
|
55
|
+
return (await http.request("GET", "/api/v1/mac/credits")).credits;
|
|
56
|
+
}
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import type { Transport } from "./http.ts";
|
|
2
|
+
import type { EmbedSettings, ViewLinkOptions } from "./types.ts";
|
|
3
|
+
/** A view link's request body: the options given, in NoMac's names. */
|
|
4
|
+
export declare function viewBody({ control, minutes, allowedOrigins, visitor }?: ViewLinkOptions): {
|
|
5
|
+
visitor?: string | undefined;
|
|
6
|
+
allowed_origins?: string[] | undefined;
|
|
7
|
+
minutes?: number | undefined;
|
|
8
|
+
control: boolean;
|
|
9
|
+
};
|
|
10
|
+
/**
|
|
11
|
+
* How the account's view links may be shown, for a platform that embeds its users' Macs and phones: the sites that may frame
|
|
12
|
+
* them, and whether each opens only for a visitor your server signed. The account's key only.
|
|
13
|
+
*/
|
|
14
|
+
export declare class Embed {
|
|
15
|
+
#private;
|
|
16
|
+
constructor(http: Transport);
|
|
17
|
+
get(): Promise<EmbedSettings>;
|
|
18
|
+
/**
|
|
19
|
+
* Replaces both settings, for every view link made from now on (the links in each phone's answer and those a Mac's or phone's
|
|
20
|
+
* token makes among them): allowedOrigins ([] for any site) and requireVisitor (newSecret first). Links made before keep theirs.
|
|
21
|
+
*/
|
|
22
|
+
set({ allowedOrigins, requireVisitor }: {
|
|
23
|
+
allowedOrigins: string[];
|
|
24
|
+
requireVisitor: boolean;
|
|
25
|
+
}): Promise<EmbedSettings>;
|
|
26
|
+
/**
|
|
27
|
+
* A new embed secret (nme_...), in this answer only: keep it on your server and sign each visitor with it (signVisitor). It
|
|
28
|
+
* replaces the one before at once; views already open keep working.
|
|
29
|
+
*/
|
|
30
|
+
newSecret(): Promise<{
|
|
31
|
+
secret: string;
|
|
32
|
+
created_at: string;
|
|
33
|
+
}>;
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* Signs a visitor for a view link, on your server: an HS256 JWT (sub: the visitor, sid: the Mac's or phone's id, exp) under the
|
|
37
|
+
* account's embed secret. Add it to the link after #visitor= when your page shows it; the link then opens for that visitor, on
|
|
38
|
+
* that Mac or phone. It lasts expiresInSeconds (300 by default, 900 at most): sign a new one for each page load. Never send the
|
|
39
|
+
* secret to a browser.
|
|
40
|
+
*/
|
|
41
|
+
export declare function signVisitor({ secret, sessionId, visitor, expiresInSeconds, now }: {
|
|
42
|
+
secret: string;
|
|
43
|
+
sessionId: string;
|
|
44
|
+
visitor: string;
|
|
45
|
+
expiresInSeconds?: number;
|
|
46
|
+
now?: number;
|
|
47
|
+
}): Promise<string>;
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.Embed = void 0;
|
|
4
|
+
exports.viewBody = viewBody;
|
|
5
|
+
exports.signVisitor = signVisitor;
|
|
6
|
+
const errors_ts_1 = require("./errors.js");
|
|
7
|
+
const EMBED = "/api/v1/embed";
|
|
8
|
+
const encoder = new TextEncoder();
|
|
9
|
+
/** How long a signed visitor may last at most: NoMac refuses a longer one. */
|
|
10
|
+
const VISITOR_MAX_SECONDS = 15 * 60;
|
|
11
|
+
/** A view link's request body: the options given, in NoMac's names. */
|
|
12
|
+
function viewBody({ control = false, minutes, allowedOrigins, visitor } = {}) {
|
|
13
|
+
return { control, ...(minutes ? { minutes } : {}), ...(allowedOrigins !== undefined ? { allowed_origins: allowedOrigins } : {}), ...(visitor !== undefined ? { visitor } : {}) };
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* How the account's view links may be shown, for a platform that embeds its users' Macs and phones: the sites that may frame
|
|
17
|
+
* them, and whether each opens only for a visitor your server signed. The account's key only.
|
|
18
|
+
*/
|
|
19
|
+
class Embed {
|
|
20
|
+
#http;
|
|
21
|
+
constructor(http) {
|
|
22
|
+
this.#http = http;
|
|
23
|
+
}
|
|
24
|
+
async get() {
|
|
25
|
+
return this.#http.request("GET", EMBED);
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Replaces both settings, for every view link made from now on (the links in each phone's answer and those a Mac's or phone's
|
|
29
|
+
* token makes among them): allowedOrigins ([] for any site) and requireVisitor (newSecret first). Links made before keep theirs.
|
|
30
|
+
*/
|
|
31
|
+
async set({ allowedOrigins, requireVisitor }) {
|
|
32
|
+
return this.#http.request("PUT", EMBED, { body: { allowed_origins: allowedOrigins, require_visitor: requireVisitor } });
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* A new embed secret (nme_...), in this answer only: keep it on your server and sign each visitor with it (signVisitor). It
|
|
36
|
+
* replaces the one before at once; views already open keep working.
|
|
37
|
+
*/
|
|
38
|
+
async newSecret() {
|
|
39
|
+
return this.#http.request("POST", `${EMBED}/secret`);
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
exports.Embed = Embed;
|
|
43
|
+
const base64url = (bytes) => {
|
|
44
|
+
let text = "";
|
|
45
|
+
for (const byte of bytes)
|
|
46
|
+
text += String.fromCharCode(byte);
|
|
47
|
+
return btoa(text).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
|
|
48
|
+
};
|
|
49
|
+
/**
|
|
50
|
+
* Signs a visitor for a view link, on your server: an HS256 JWT (sub: the visitor, sid: the Mac's or phone's id, exp) under the
|
|
51
|
+
* account's embed secret. Add it to the link after #visitor= when your page shows it; the link then opens for that visitor, on
|
|
52
|
+
* that Mac or phone. It lasts expiresInSeconds (300 by default, 900 at most): sign a new one for each page load. Never send the
|
|
53
|
+
* secret to a browser.
|
|
54
|
+
*/
|
|
55
|
+
async function signVisitor({ secret, sessionId, visitor, expiresInSeconds = 300, now = Date.now() }) {
|
|
56
|
+
if (typeof secret !== "string" || !secret.startsWith("nme_"))
|
|
57
|
+
throw new errors_ts_1.NoMacError("invalid_secret", "Sign with the account's embed secret (nme_...), from client.embed.newSecret(), never the API key.");
|
|
58
|
+
if (!/^ses_[A-Za-z0-9_-]{1,80}$/.test(sessionId))
|
|
59
|
+
throw new errors_ts_1.NoMacError("invalid_request", "sessionId: the Mac's or the phone's id (ses_...).");
|
|
60
|
+
if (!/^[A-Za-z0-9._:@-]{1,128}$/.test(visitor))
|
|
61
|
+
throw new errors_ts_1.NoMacError("invalid_request", "visitor: your user's id, letters, digits and . _ : @ -, up to 128.");
|
|
62
|
+
if (!Number.isInteger(expiresInSeconds) || expiresInSeconds < 1 || expiresInSeconds > VISITOR_MAX_SECONDS)
|
|
63
|
+
throw new errors_ts_1.NoMacError("invalid_request", `expiresInSeconds: a whole number from 1 to ${VISITOR_MAX_SECONDS}.`);
|
|
64
|
+
const issued = Math.floor(now / 1000);
|
|
65
|
+
const header = base64url(encoder.encode(JSON.stringify({ alg: "HS256", typ: "JWT" })));
|
|
66
|
+
const payload = base64url(encoder.encode(JSON.stringify({ sub: visitor, sid: sessionId, iat: issued, exp: issued + expiresInSeconds })));
|
|
67
|
+
const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
|
|
68
|
+
const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(`${header}.${payload}`)));
|
|
69
|
+
return `${header}.${payload}.${base64url(mac)}`;
|
|
70
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/** NoMac's refusal, in its own words: code (stable, for code to branch on), message (for a person), the HTTP status (0 when none). */
|
|
2
|
+
export declare class NoMacError extends Error {
|
|
3
|
+
readonly code: string;
|
|
4
|
+
readonly status: number;
|
|
5
|
+
readonly details: unknown;
|
|
6
|
+
/** A keyed request's key (a start, a command): the same request with it reads the first one's result, never doing it twice. */
|
|
7
|
+
requestKey?: string;
|
|
8
|
+
constructor(code: string, message: string, status?: number, details?: unknown);
|
|
9
|
+
}
|
|
10
|
+
/** A request key: the same key makes a retry the same request (a start, a command, a tool call, a fetch). */
|
|
11
|
+
export declare const requestKey: (prefix?: string) => string;
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.requestKey = exports.NoMacError = void 0;
|
|
4
|
+
/** NoMac's refusal, in its own words: code (stable, for code to branch on), message (for a person), the HTTP status (0 when none). */
|
|
5
|
+
class NoMacError extends Error {
|
|
6
|
+
code;
|
|
7
|
+
status;
|
|
8
|
+
details;
|
|
9
|
+
/** A keyed request's key (a start, a command): the same request with it reads the first one's result, never doing it twice. */
|
|
10
|
+
requestKey;
|
|
11
|
+
constructor(code, message, status = 0, details = undefined) {
|
|
12
|
+
super(message);
|
|
13
|
+
this.name = "NoMacError";
|
|
14
|
+
this.code = code;
|
|
15
|
+
this.status = status;
|
|
16
|
+
this.details = details;
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
exports.NoMacError = NoMacError;
|
|
20
|
+
/** A request key: the same key makes a retry the same request (a start, a command, a tool call, a fetch). */
|
|
21
|
+
const requestKey = (prefix = "sdk") => `${prefix}-${crypto.randomUUID()}`;
|
|
22
|
+
exports.requestKey = requestKey;
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
export declare const DEFAULT_BASE_URL = "https://nomac.app";
|
|
2
|
+
export declare const sleep: (ms: number) => Promise<void>;
|
|
3
|
+
export interface ClientOptions {
|
|
4
|
+
/** The account's API key (nmk_...). NOMAC_API_KEY when neither it nor token is passed. */
|
|
5
|
+
apiKey?: string;
|
|
6
|
+
/** One Mac's token (nmm_...) or one phone's (nmp_...), from mac.token() or phone.token(): its own Mac or phone only. */
|
|
7
|
+
token?: string;
|
|
8
|
+
/** https://nomac.app by default. */
|
|
9
|
+
baseUrl?: string;
|
|
10
|
+
/** A fetch to use instead of the global one (a proxy, a test). */
|
|
11
|
+
fetch?: typeof fetch;
|
|
12
|
+
}
|
|
13
|
+
export interface RequestOptions {
|
|
14
|
+
body?: unknown;
|
|
15
|
+
/** The same key makes a retry the same request: NoMac answers the first one's result. */
|
|
16
|
+
idempotencyKey?: string;
|
|
17
|
+
/** How long one try may take, in milliseconds (90 s by default). */
|
|
18
|
+
timeoutMs?: number;
|
|
19
|
+
}
|
|
20
|
+
/** What the resources reach NoMac with: JSON calls, and bytes to and from links NoMac signed. */
|
|
21
|
+
export interface Transport {
|
|
22
|
+
request<T = Record<string, any>>(method: string, path: string, options?: RequestOptions): Promise<T>;
|
|
23
|
+
upload(url: string, data: Uint8Array | ArrayBuffer | Blob): Promise<void>;
|
|
24
|
+
download(url: string): Promise<Uint8Array>;
|
|
25
|
+
downloadStream(url: string): Promise<ReadableStream<Uint8Array>>;
|
|
26
|
+
}
|
|
27
|
+
export declare class Http implements Transport {
|
|
28
|
+
#private;
|
|
29
|
+
constructor(options?: ClientOptions);
|
|
30
|
+
/**
|
|
31
|
+
* One call to the REST API: JSON in and out, NoMac's error as a NoMacError. A read, a stop and a request with a key are sent
|
|
32
|
+
* again up to five times when NoMac is busy or does not answer, and a keyed request NoMac is still starting (operation_pending)
|
|
33
|
+
* is asked again with its key. A request without a key is sent again only after a 429 rate_limited, which nothing did. A
|
|
34
|
+
* keyed request's error carries its key (requestKey), so its result can be read later instead of doing it twice.
|
|
35
|
+
*/
|
|
36
|
+
request<T = Record<string, any>>(method: string, path: string, { body, idempotencyKey, timeoutMs }?: RequestOptions): Promise<T>;
|
|
37
|
+
/** PUTs bytes (a Blob as it is, never read into memory first) to a link NoMac signed: no NoMac credential goes with them. */
|
|
38
|
+
upload(url: string, data: Uint8Array | ArrayBuffer | Blob): Promise<void>;
|
|
39
|
+
/** GETs bytes from a link NoMac signed (a download link): no NoMac credential goes with them. */
|
|
40
|
+
download(url: string): Promise<Uint8Array<ArrayBuffer>>;
|
|
41
|
+
/** The same download as a stream, so a large file never sits in memory. */
|
|
42
|
+
downloadStream(url: string): Promise<ReadableStream<Uint8Array>>;
|
|
43
|
+
}
|
|
44
|
+
/** Base64 to bytes and back, in any runtime with atob and btoa. */
|
|
45
|
+
export declare function fromBase64(data: string): Uint8Array;
|
|
46
|
+
export declare function toBase64(bytes: Uint8Array): string;
|
|
47
|
+
export declare function asBytes(data: string | Uint8Array | ArrayBuffer | Blob): Promise<Uint8Array>;
|
|
48
|
+
export declare const hex: (bytes: ArrayBuffer | Uint8Array) => string;
|