nomac 0.1.0__tar.gz

nomac-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+.mypy_cache/
+.pytest_cache/
+__pycache__/
+dist/
+uv.lock

nomac-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NoMac
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nomac-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: nomac
+Version: 0.1.0
+Summary: NoMac from Python: iPhone and iPad Simulators in the cloud for a platform's users and agents, their tools, live view, saved state, tokens and webhooks.
+Project-URL: Homepage, https://nomac.app/platform
+Project-URL: Documentation, https://nomac.app/docs/simulator
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ios,iphone,mcp,nomac,simulator,xcode
+Classifier: Framework :: AsyncIO
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# nomac
+
+[NoMac Simulator](https://nomac.app/platform) from Python: iPhone and iPad Simulators in the cloud, for a platform's users and agents. Start a phone, build and run a native app on it, read and tap its screen by label, show it live in your page, save its state, and hear when it is ready or ends.
+
+```sh
+pip install nomac
+```
+
+Python 3.10 and later, one dependency (`httpx`), typed. `NoMac` for sync code, `AsyncNoMac` for asyncio: the same calls, awaited.
+
+```python
+from nomac import NoMac
+
+nomac = NoMac()  # NOMAC_API_KEY from the environment
+phone = nomac.phones.start(label="user-42", reuse=True)
+phone.wait_until_ready()
+root = phone.fetch_git("https://github.com/acme/app", token=github_token)["root"]
+print(phone.tool("app_run", path=root, scheme="App").text)
+phone.stop()
+```
+
+```python
+from nomac import AsyncNoMac
+
+async with AsyncNoMac() as nomac:
+    phone = await nomac.phones.start(label="user-42", reuse=True)
+    await phone.wait_until_ready()
+    print((await phone.tool("ui_look")).text)
+    await phone.stop()
+```
+
+A phone costs $0.80 an hour, billed per minute from the account's prepaid credit, with a one-minute minimum. Waiting in line is free.
+
+## Phones
+
+`nomac.phones.start(device=, label=, reuse=, limits=)` starts a phone and answers it at once, usually `queued`; `phone.wait_until_ready()` follows it. A phone from the pool is ready in seconds. When every phone is in use, the start waits in line, free, up to 5 minutes.
+
+- `device`: `"iphone"` (iPhone 17 Pro, the default), `"ipad"` (iPad Pro 11-inch (M5)) or `"iphone-pro-max"` (iPhone 17 Pro Max), all on iOS 27.
+- `label`: your own name for the phone, such as your user's id: letters, digits and `. _ : @ -`, up to 64.
+- `reuse`: with `label`, answer the live phone with that label instead of starting another (`phone.reused`).
+- `limits`: `max_duration_seconds` (7,200 by default, 28,800 at most), `idle_timeout_seconds` (600 by default, 60 to 3,600) and `spend_cap_microunits` (`"5000000"`, $5, by default).
+
+An account runs two phones at once by default; [NoMac Platform](https://nomac.app/platform) runs more. A retry of a start with the same `idempotency_key` answers the same phone, never a second one.
+
+`nomac.phones.list(label=)` lists the account's phones, newest first, and `nomac.phones.get(id)` reads one. `phone.session` has its state, device, label, cost and deadlines; `phone.refresh()` reads it again. `phone.extend(minutes=)` keeps a running phone longer, up to 8 hours in all. `phone.stop()` ends it: its apps and data go with it, and its workspace (projects and build output) stays for the next phone with the same label, so the next build is incremental.
+
+## Tools
+
+`phone.tool(name, arguments)` runs one of [simulator-use](https://simulator-use.dev)'s tools on the phone, its arguments as a dict or as keywords, and answers a `ToolResult`: `text` says what happened and what to do next, `content` has its text and images, `is_error`, and `stop_notice` in the phone's last 15 minutes. A long build is followed to its end.
+
+| Tool | |
+| --- | --- |
+| `app_run` | Builds an Xcode project or workspace (`path`, `scheme`) with Xcode 27.1, installs it and launches it. |
+| `tests_run` | Runs XCTest and XCUITest, each case's result as it finishes. |
+| `ui_look` | The screen as text, one line per element with its label and position. |
+| `ui_act` | Taps, types, swipes and keys by label: `steps=['tap "Sign In"', "fill #email a@b.co"]`. |
+| `app_control` | Installs, launches and terminates apps, opens links, sets permissions, appearance, locale, time zone and location. |
+| `app_logs`, `screen_record`, `devices`, `job_status`, `job_cancel` | Logs, video, the phone and Xcodes, long jobs. |
+
+Projects reach the phone's workspace with `phone.fetch_git(url, ref=, token=)` or `phone.upload_archive(data, name=)` (bytes or a file's path: a `.tar.gz` or `.zip` of a project, or of a `.app` built for the Simulator, up to 2 GiB). Both answer `root`, the path `app_run` and `tests_run` take; only what changed is written.
+
+A private repository on github.com, gitlab.com or bitbucket.org takes its token one of two ways, and it goes only to that host:
+
+- `token`: the token itself, sent with this fetch and kept nowhere, not even for the phone's next fetch. Your user's token stays with you, and a short-lived one (GitHub's one-hour tokens) works. A phone's token may send one.
+- `secret`: the name of one of the account's own secrets that holds it, for your own repositories (the account's key only).
+
+Values your app needs go with the run, as `env` on `app_run` (`"API_URL=https://staging.example KEY=..."`): the phone keeps them for its relaunches until it stops, and they are erased with it.
+
+## Live view and your users
+
+`phone.links["view"]` (watch) and `phone.links["control"]` (use) are links a person opens with no NoMac sign-in; `phone.view_link(control=True, minutes=120)` makes one for your user. [`@nomac/phone`](https://www.npmjs.com/package/@nomac/phone) embeds it in your page.
+
+`phone.token(minutes=)` gives a token for that phone only, to hand your own user or agent: `NoMac(token=...)` reaches that phone's tools, files, state, view and replay until the token expires (2 hours by default, a day at most). It cannot start, list or stop phones, make another token, use the account's secrets, or reach your webhooks. `phone.revoke_tokens()` revokes every token and link of the phone made so far.
+
+Phones are kept apart by `label`: a workspace and saved states are shared only by phones with the same label. Give each of your users their own label, and one user's phone, or its token, never reaches another's.
+
+## Saved state and replays
+
+`phone.save_state("signed-in")` keeps the phone's apps, their data, its keychain and permissions for the phones with its label; `phone.restore_state("signed-in")` puts them back onto any of them of the same model and iOS. `phone.list_states()` and `phone.delete_state(name)` manage them. Every phone is recorded: `phone.replay()` answers its video and its calls (typed text left out) once it has stopped, kept 7 days.
+
+## Deleting a user's data
+
+When one of your users deletes their account, `nomac.labels.delete("user-42")` deletes what NoMac keeps for that label: its saved states, its phones' replays and file copies, and its workspace (the key to its encrypted volume is destroyed at once, so it never opens again; the host deletes the volume on its own sweep). It answers `{"deleted": {"states", "workspaces", "replays", "files"}}`; a repeat finds nothing left. Stop the label's phones first (`label_in_use`); for 15 minutes after the last one ends its replay is still being saved (`label_busy`, `details["retry_after_seconds"]`). The phones' records (times and cost, under the label) stay for billing, so use your own user id as the label, not an email.
+
+## Webhooks
+
+```python
+hook = nomac.webhooks.create("https://platform.example/nomac", events=["phone.ready", "phone.ended"])
+# Keep hook["secret"]: it is shown once.
+```
+
+Check every delivery before trusting it, with the raw body as received:
+
+```python
+from nomac import verify_webhook
+
+event = verify_webhook(request.body, request.headers["nomac-signature"], os.environ["NOMAC_WEBHOOK_SECRET"])
+if event["type"] == "phone.ended":
+    release(event["data"]["session"]["label"], event["data"]["reason"])
+```
+
+`phone.ended` carries the label, the time billed and the cost, and why it ended (`stopped`, `idle`, `time_limit`, `spend_cap`, `credit`, `crashed`, `no_capacity` or `start_failed`). A delivery can come more than once: key on its `id`. `nomac.webhooks.list()`, `delete(id)` and `deliveries(id)` manage them.
+
+## Errors
+
+A refusal is a `NoMacError` with NoMac's `code` (for code to branch on), `message` (for a person), HTTP `status` and `details`, such as `session_limit_reached` (409) or `insufficient_credit` (402). A read, a stop and any request with a request key are sent again when NoMac is busy for a moment.
+
+The REST API it calls is at [nomac.app/docs/simulator](https://nomac.app/docs/simulator); `nomac.request(method, path, body=, idempotency_key=)` calls it directly.
+
+MIT licensed.

nomac-0.1.0/README.md

@@ -0,0 +1,110 @@
+# nomac
+
+[NoMac Simulator](https://nomac.app/platform) from Python: iPhone and iPad Simulators in the cloud, for a platform's users and agents. Start a phone, build and run a native app on it, read and tap its screen by label, show it live in your page, save its state, and hear when it is ready or ends.
+
+```sh
+pip install nomac
+```
+
+Python 3.10 and later, one dependency (`httpx`), typed. `NoMac` for sync code, `AsyncNoMac` for asyncio: the same calls, awaited.
+
+```python
+from nomac import NoMac
+
+nomac = NoMac()  # NOMAC_API_KEY from the environment
+phone = nomac.phones.start(label="user-42", reuse=True)
+phone.wait_until_ready()
+root = phone.fetch_git("https://github.com/acme/app", token=github_token)["root"]
+print(phone.tool("app_run", path=root, scheme="App").text)
+phone.stop()
+```
+
+```python
+from nomac import AsyncNoMac
+
+async with AsyncNoMac() as nomac:
+    phone = await nomac.phones.start(label="user-42", reuse=True)
+    await phone.wait_until_ready()
+    print((await phone.tool("ui_look")).text)
+    await phone.stop()
+```
+
+A phone costs $0.80 an hour, billed per minute from the account's prepaid credit, with a one-minute minimum. Waiting in line is free.
+
+## Phones
+
+`nomac.phones.start(device=, label=, reuse=, limits=)` starts a phone and answers it at once, usually `queued`; `phone.wait_until_ready()` follows it. A phone from the pool is ready in seconds. When every phone is in use, the start waits in line, free, up to 5 minutes.
+
+- `device`: `"iphone"` (iPhone 17 Pro, the default), `"ipad"` (iPad Pro 11-inch (M5)) or `"iphone-pro-max"` (iPhone 17 Pro Max), all on iOS 27.
+- `label`: your own name for the phone, such as your user's id: letters, digits and `. _ : @ -`, up to 64.
+- `reuse`: with `label`, answer the live phone with that label instead of starting another (`phone.reused`).
+- `limits`: `max_duration_seconds` (7,200 by default, 28,800 at most), `idle_timeout_seconds` (600 by default, 60 to 3,600) and `spend_cap_microunits` (`"5000000"`, $5, by default).
+
+An account runs two phones at once by default; [NoMac Platform](https://nomac.app/platform) runs more. A retry of a start with the same `idempotency_key` answers the same phone, never a second one.
+
+`nomac.phones.list(label=)` lists the account's phones, newest first, and `nomac.phones.get(id)` reads one. `phone.session` has its state, device, label, cost and deadlines; `phone.refresh()` reads it again. `phone.extend(minutes=)` keeps a running phone longer, up to 8 hours in all. `phone.stop()` ends it: its apps and data go with it, and its workspace (projects and build output) stays for the next phone with the same label, so the next build is incremental.
+
+## Tools
+
+`phone.tool(name, arguments)` runs one of [simulator-use](https://simulator-use.dev)'s tools on the phone, its arguments as a dict or as keywords, and answers a `ToolResult`: `text` says what happened and what to do next, `content` has its text and images, `is_error`, and `stop_notice` in the phone's last 15 minutes. A long build is followed to its end.
+
+| Tool | |
+| --- | --- |
+| `app_run` | Builds an Xcode project or workspace (`path`, `scheme`) with Xcode 27.1, installs it and launches it. |
+| `tests_run` | Runs XCTest and XCUITest, each case's result as it finishes. |
+| `ui_look` | The screen as text, one line per element with its label and position. |
+| `ui_act` | Taps, types, swipes and keys by label: `steps=['tap "Sign In"', "fill #email a@b.co"]`. |
+| `app_control` | Installs, launches and terminates apps, opens links, sets permissions, appearance, locale, time zone and location. |
+| `app_logs`, `screen_record`, `devices`, `job_status`, `job_cancel` | Logs, video, the phone and Xcodes, long jobs. |
+
+Projects reach the phone's workspace with `phone.fetch_git(url, ref=, token=)` or `phone.upload_archive(data, name=)` (bytes or a file's path: a `.tar.gz` or `.zip` of a project, or of a `.app` built for the Simulator, up to 2 GiB). Both answer `root`, the path `app_run` and `tests_run` take; only what changed is written.
+
+A private repository on github.com, gitlab.com or bitbucket.org takes its token one of two ways, and it goes only to that host:
+
+- `token`: the token itself, sent with this fetch and kept nowhere, not even for the phone's next fetch. Your user's token stays with you, and a short-lived one (GitHub's one-hour tokens) works. A phone's token may send one.
+- `secret`: the name of one of the account's own secrets that holds it, for your own repositories (the account's key only).
+
+Values your app needs go with the run, as `env` on `app_run` (`"API_URL=https://staging.example KEY=..."`): the phone keeps them for its relaunches until it stops, and they are erased with it.
+
+## Live view and your users
+
+`phone.links["view"]` (watch) and `phone.links["control"]` (use) are links a person opens with no NoMac sign-in; `phone.view_link(control=True, minutes=120)` makes one for your user. [`@nomac/phone`](https://www.npmjs.com/package/@nomac/phone) embeds it in your page.
+
+`phone.token(minutes=)` gives a token for that phone only, to hand your own user or agent: `NoMac(token=...)` reaches that phone's tools, files, state, view and replay until the token expires (2 hours by default, a day at most). It cannot start, list or stop phones, make another token, use the account's secrets, or reach your webhooks. `phone.revoke_tokens()` revokes every token and link of the phone made so far.
+
+Phones are kept apart by `label`: a workspace and saved states are shared only by phones with the same label. Give each of your users their own label, and one user's phone, or its token, never reaches another's.
+
+## Saved state and replays
+
+`phone.save_state("signed-in")` keeps the phone's apps, their data, its keychain and permissions for the phones with its label; `phone.restore_state("signed-in")` puts them back onto any of them of the same model and iOS. `phone.list_states()` and `phone.delete_state(name)` manage them. Every phone is recorded: `phone.replay()` answers its video and its calls (typed text left out) once it has stopped, kept 7 days.
+
+## Deleting a user's data
+
+When one of your users deletes their account, `nomac.labels.delete("user-42")` deletes what NoMac keeps for that label: its saved states, its phones' replays and file copies, and its workspace (the key to its encrypted volume is destroyed at once, so it never opens again; the host deletes the volume on its own sweep). It answers `{"deleted": {"states", "workspaces", "replays", "files"}}`; a repeat finds nothing left. Stop the label's phones first (`label_in_use`); for 15 minutes after the last one ends its replay is still being saved (`label_busy`, `details["retry_after_seconds"]`). The phones' records (times and cost, under the label) stay for billing, so use your own user id as the label, not an email.
+
+## Webhooks
+
+```python
+hook = nomac.webhooks.create("https://platform.example/nomac", events=["phone.ready", "phone.ended"])
+# Keep hook["secret"]: it is shown once.
+```
+
+Check every delivery before trusting it, with the raw body as received:
+
+```python
+from nomac import verify_webhook
+
+event = verify_webhook(request.body, request.headers["nomac-signature"], os.environ["NOMAC_WEBHOOK_SECRET"])
+if event["type"] == "phone.ended":
+    release(event["data"]["session"]["label"], event["data"]["reason"])
+```
+
+`phone.ended` carries the label, the time billed and the cost, and why it ended (`stopped`, `idle`, `time_limit`, `spend_cap`, `credit`, `crashed`, `no_capacity` or `start_failed`). A delivery can come more than once: key on its `id`. `nomac.webhooks.list()`, `delete(id)` and `deliveries(id)` manage them.
+
+## Errors
+
+A refusal is a `NoMacError` with NoMac's `code` (for code to branch on), `message` (for a person), HTTP `status` and `details`, such as `session_limit_reached` (409) or `insufficient_credit` (402). A read, a stop and any request with a request key are sent again when NoMac is busy for a moment.
+
+The REST API it calls is at [nomac.app/docs/simulator](https://nomac.app/docs/simulator); `nomac.request(method, path, body=, idempotency_key=)` calls it directly.
+
+MIT licensed.

nomac-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nomac"
+version = "0.1.0"
+description = "NoMac from Python: iPhone and iPad Simulators in the cloud for a platform's users and agents, their tools, live view, saved state, tokens and webhooks."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27"]
+keywords = ["ios", "simulator", "iphone", "xcode", "agents", "mcp", "nomac"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Typing :: Typed",
+  "Framework :: AsyncIO",
+]
+
+[project.urls]
+Homepage = "https://nomac.app/platform"
+Documentation = "https://nomac.app/docs/simulator"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nomac"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/nomac", "tests", "README.md", "LICENSE", "pyproject.toml"]

nomac-0.1.0/src/nomac/__init__.py

@@ -0,0 +1,11 @@
+"""
+NoMac from Python: iPhone and iPad Simulators in the cloud for a platform's users and agents (NoMac Simulator), their
+tools, live view, saved state, tokens and webhooks. NoMac for sync code, AsyncNoMac for asyncio.
+"""
+
+from ._async import AsyncNoMac, AsyncPhone
+from ._base import NoMacError, ToolResult, request_key, verify_webhook
+from ._sync import NoMac, Phone
+
+__all__ = ["NoMac", "AsyncNoMac", "Phone", "AsyncPhone", "NoMacError", "ToolResult", "request_key", "verify_webhook"]
+__version__ = "0.1.0"

nomac-0.1.0/src/nomac/_async.py

@@ -0,0 +1,296 @@
+"""The async client: the same calls as NoMac, awaited, over httpx.AsyncClient."""
+
+from __future__ import annotations
+
+import asyncio
+import builtins
+import os
+import time
+from typing import Any, AsyncIterator, Mapping
+from urllib.parse import quote
+
+import httpx
+
+from . import _base
+from ._base import ENDED, LABELS, SESSIONS, WEBHOOKS, NoMacError, ToolResult, request_key
+
+
+class AsyncNoMac:
+    """
+    A client for an account (its API key, nmk_...) or for one phone (the token a platform hands its own user,
+    nmp_...), every call awaited. NOMAC_API_KEY from the environment by default. Close it, or use it in an async with block.
+    """
+
+    def __init__(self, api_key: str | None = None, *, token: str | None = None, base_url: str = _base.DEFAULT_BASE_URL,
+                 http_client: httpx.AsyncClient | None = None, timeout: float = 90.0) -> None:
+        self._auth = f"Bearer {_base.credential(api_key, token)}"
+        self._base = base_url.rstrip("/")
+        self._timeout = timeout
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+        self._own_http = http_client is None
+        self.phones = AsyncPhones(self)
+        self.labels = AsyncLabels(self)
+        self.webhooks = AsyncWebhooks(self)
+
+    def phone(self, id: str) -> AsyncPhone:
+        """A phone by its id, without reading it (a phone's token reaches its own only)."""
+        return AsyncPhone(self, {"id": id})
+
+    async def request(self, method: str, path: str, *, body: Any = None, idempotency_key: str | None = None, timeout: float | None = None) -> dict[str, Any]:
+        """
+        One call to the REST API: JSON in and out, NoMac's error as a NoMacError. A read, a stop, a request with a key,
+        and any request NoMac answered 429 are sent again up to three times when NoMac is busy or does not answer.
+        """
+        again = _base.repeatable(method, idempotency_key)
+        for attempt in range(1, _base.ATTEMPTS + 1):
+            try:
+                response = await self._http.request(method, f"{self._base}{path}", headers=_base.headers(self._auth, idempotency_key, body is not None),
+                                                    json=body, timeout=timeout or self._timeout)
+            except httpx.HTTPError as error:
+                if again and attempt < _base.ATTEMPTS:
+                    await asyncio.sleep(_base.pause_seconds(attempt))
+                    continue
+                raise _base.unreachable(error) from None
+            value = _base.answer(method, path, attempt, again, response.status_code, response.text, response.headers.get("retry-after"))
+            if isinstance(value, dict):
+                return value
+            await asyncio.sleep(value)
+        raise NoMacError("unreachable", "NoMac did not answer.")
+
+    async def _upload(self, url: str, data: bytes | None, path: str | None, size: int) -> None:
+        """PUTs an archive to a link NoMac signed (an upload link): no NoMac credential goes with it."""
+        headers = {"content-length": str(size)}
+        if path is None:
+            response = await self._http.put(url, content=data, headers=headers, timeout=30 * 60)
+        else:
+            response = await self._http.put(url, content=_pieces(path), headers=headers, timeout=30 * 60)
+        if response.status_code >= 300:
+            raise NoMacError("upload_failed", f"The upload was refused ({response.status_code}); ask for a new upload link.", response.status_code)
+
+    async def close(self) -> None:
+        if self._own_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncNoMac:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+
+async def _pieces(path: str) -> AsyncIterator[bytes]:
+    """A file in pieces, read off the event loop."""
+    with open(path, "rb") as file:
+        while piece := await asyncio.to_thread(file.read, 1 << 20):
+            yield piece
+
+
+class AsyncPhones:
+    def __init__(self, client: AsyncNoMac) -> None:
+        self._client = client
+
+    async def start(self, *, device: str | None = None, label: str | None = None, reuse: bool | None = None, limits: Mapping[str, Any] | None = None,
+                    idempotency_key: str | None = None) -> AsyncPhone:
+        """
+        Starts a phone: device ("iphone", "ipad" or "iphone-pro-max"), label (your user's id), reuse, limits. With reuse
+        and a label, the live phone with that label is answered instead of a new one (phone.reused). A full Simulator
+        host queues the start, free, for up to 5 minutes: wait_until_ready() follows it. The same idempotency_key
+        retries a start.
+        """
+        answer = await self._client.request("POST", SESSIONS, body=_base.start_body(device, label, reuse, limits), idempotency_key=idempotency_key or request_key("start"))
+        return AsyncPhone(self._client, answer["session"], answer.get("links"), bool(answer.get("reused")))
+
+    async def list(self, *, label: str | None = None) -> builtins.list[AsyncPhone]:
+        """The account's phones, newest first; with label, the ones a platform named so."""
+        answer = await self._client.request("GET", f"{SESSIONS}?label={quote(label, safe='')}" if label else SESSIONS)
+        return [AsyncPhone(self._client, session) for session in _base.rows(answer, "sessions")]
+
+    async def get(self, id: str) -> AsyncPhone:
+        return await AsyncPhone(self._client, {"id": id}).refresh()
+
+
+class AsyncPhone:
+    """A phone: its session (state, device, label, cost, deadlines) and links, and what can be done with it."""
+
+    def __init__(self, client: AsyncNoMac, session: dict[str, Any], links: dict[str, Any] | None = None, reused: bool = False) -> None:
+        self._client = client
+        self.id: str = session["id"]
+        self.session = session
+        self.links = links
+        self.reused = reused
+        # In its last 15 minutes before a limit or the credit's end: when it stops, why and what to do first.
+        self.stop_notice: dict[str, Any] | None = None
+
+    @property
+    def state(self) -> str | None:
+        return self.session.get("state")
+
+    def _path(self, rest: str = "") -> str:
+        return f"{SESSIONS}/{quote(self.id, safe='')}{rest}"
+
+    async def refresh(self) -> AsyncPhone:
+        answer = await self._client.request("GET", self._path())
+        self.session = answer["session"]
+        self.links = answer.get("links") or self.links
+        self.stop_notice = answer.get("stop_notice")
+        return self
+
+    async def wait_until_ready(self, *, timeout: float = 6 * 60, interval: float = 1.0) -> AsyncPhone:
+        """Waits until the phone is ready (a phone from the pool takes seconds; a queued one up to 5 minutes)."""
+        by = time.monotonic() + timeout
+        while True:
+            if self.state == "ready":
+                return self
+            if self.state in ENDED:
+                raise NoMacError("phone_ended", f"The phone ended before it was ready ({self.session.get('failure_code') or self.state}).", 0, self.session)
+            if time.monotonic() >= by:
+                raise NoMacError("timeout", f"The phone was not ready within {round(timeout)} s ({self.state}).", 0, self.session)
+            await asyncio.sleep(interval)
+            await self.refresh()
+
+    async def tool(self, name: str, arguments: Mapping[str, Any] | None = None, /, *, idempotency_key: str | None = None, interval: float = 1.0,
+                   timeout: float = 60 * 60, wait_for_jobs: bool = True, **more: Any) -> ToolResult:
+        """
+        Runs one of simulator-use's tools on the phone (ui_look, ui_act, app_run, tests_run, app_control, ...), its
+        arguments as a dict or as keywords, and waits for its result. A long build that hands back a job is followed
+        with job_status until it ends, unless wait_for_jobs is False.
+        """
+        by = time.monotonic() + timeout
+        result = await self._call(name, _base.tool_arguments(arguments, more), idempotency_key or request_key(name), by, interval)
+        job = _base.job_of(result) if wait_for_jobs else None
+        # Each job_status waits up to 40 s for the job; one still running answers "job_status again".
+        for _ in range(120 if job else 0):
+            result = await self._call("job_status", {"job_id": job}, request_key("job_status"), by, interval)
+            if result.is_error or not _base.STILL_RUNNING.search(result.text):
+                break
+            if time.monotonic() >= by:
+                raise NoMacError("timeout", f'{name}\'s job {job} was still running; read it later with phone.tool("job_status", job_id="{job}").', 0, result.raw)
+        return result
+
+    async def _call(self, name: str, arguments: dict[str, Any], key: str, by: float, interval: float) -> ToolResult:
+        answer = await self._client.request("POST", self._path(f"/tools/{quote(name, safe='')}"), body=arguments, idempotency_key=key)
+        while answer.get("state") == "running" and isinstance(answer.get("id"), str):
+            if time.monotonic() >= by:
+                raise NoMacError("timeout", f'{name} was still running; cancel it with phone.cancel("{answer["id"]}") or read it later.', 0, answer)
+            await asyncio.sleep(interval)
+            answer = await self._client.request("GET", self._path(f"/calls/{answer['id']}"))
+        return _base.tool_result(name, answer)
+
+    async def cancel(self, call_id: str) -> dict[str, Any]:
+        """Stops a running tool call; a finished one is answered as it is."""
+        return await self._client.request("POST", self._path(f"/calls/{quote(call_id, safe='')}/cancel"))
+
+    # An operation the phone runs for a while (a fetch, a save): the same request with the same key reads it until done.
+    async def _operation(self, path: str, body: dict[str, Any], key: str, timeout: float | None, interval: float = 1.0) -> dict[str, Any]:
+        by = time.monotonic() + (30 * 60 if timeout is None else timeout)
+        while True:
+            answer = await self._client.request("POST", self._path(path), body=body, idempotency_key=key)
+            if _base.operation_answer(answer, key, by):
+                return answer
+            await asyncio.sleep(interval)
+
+    async def fetch_git(self, url: str, *, ref: str | None = None, token: str | None = None, secret: str | None = None,
+                        idempotency_key: str | None = None, timeout: float | None = None) -> dict[str, Any]:
+        """
+        A git repository into the phone's workspace. A private repository's token is token itself, used for this fetch
+        and kept nowhere (a phone's token may send one), or secret, the name of the account's secret holding it;
+        github.com, gitlab.com and bitbucket.org only. Answers {"root", "commit"}: root is the path app_run and tests_run take.
+        """
+        return await self._operation("/sync/git", _base.git_body(url, ref, token, secret), idempotency_key or request_key("git"), timeout)
+
+    async def upload_archive(self, data: bytes | bytearray | memoryview | str | os.PathLike[str], *, name: str | None = None,
+                             idempotency_key: str | None = None, timeout: float | None = None) -> dict[str, Any]:
+        """
+        An archive (a .tar.gz or .zip of a project, or of a .app built for the Simulator; bytes or a file's path) into
+        the phone's workspace under name, up to 2 GiB: uploaded to storage, then unpacked, only what differs written.
+        Answers {"root", "app"}.
+        """
+        raw, path, size, sha256 = _base.archive_bytes(data)
+        link = await self._client.request("POST", self._path("/sync/upload"), body={"size": size, "sha256": sha256})
+        await self._client._upload(link["upload_url"], raw, path, size)
+        return await self._operation("/sync/fetch", {"sha256": sha256, **({"name": name} if name else {})}, idempotency_key or request_key("upload"), timeout)
+
+    async def view_link(self, *, control: bool = False, minutes: int | None = None) -> dict[str, Any]:
+        """A link to the phone's live view for a person, no sign-in: watch only, or control=True. {"url", "expires_at"}."""
+        return await self._client.request("POST", self._path("/view"), body={"control": control, **({"minutes": minutes} if minutes else {})})
+
+    async def token(self, *, minutes: int | None = None) -> dict[str, Any]:
+        """
+        A token for this phone only, to hand a platform's own user or agent: AsyncNoMac(token=...) reaches its tools, files,
+        state and view, until it expires (2 hours by default, a day at most) or the phone ends.
+        """
+        return await self._client.request("POST", self._path("/token"), body={"minutes": minutes} if minutes else {})
+
+    async def revoke_tokens(self) -> dict[str, Any]:
+        """Revokes every token and link of this phone made so far, with the account's key; the phone runs on."""
+        return await self._client.request("DELETE", self._path("/token"))
+
+    async def replay(self) -> dict[str, Any]:
+        """The phone's replay: recording, saving after its stop, then ready with its video, its calls and a link."""
+        return await self._client.request("GET", self._path("/replay"))
+
+    async def save_state(self, name: str, *, idempotency_key: str | None = None, timeout: float | None = None) -> dict[str, Any]:
+        """Saves the phone's apps, their data, its keychain and permissions under name, for the phones with its label."""
+        return await self._operation("/state", {"action": "save", "name": name}, idempotency_key or request_key("state"), timeout)
+
+    async def restore_state(self, name: str, *, idempotency_key: str | None = None, timeout: float | None = None) -> dict[str, Any]:
+        """Puts a saved state back, onto a phone of the same model and iOS."""
+        return await self._operation("/state", {"action": "restore", "name": name}, idempotency_key or request_key("state"), timeout)
+
+    async def list_states(self) -> builtins.list[dict[str, Any]]:
+        return _base.rows(await self._operation("/state", {"action": "list"}, request_key("state"), None), "states")
+
+    async def delete_state(self, name: str) -> dict[str, Any]:
+        return await self._operation("/state", {"action": "delete", "name": name}, request_key("state"), None)
+
+    async def extend(self, *, minutes: int | None = None) -> AsyncPhone:
+        """
+        Keeps the phone running longer: its time limit goes up by minutes (60 by default, up to 8 hours in all), and its
+        spend cap with it. The account's key only. Not sent again by itself: a repeat adds more time.
+        """
+        answer = await self._client.request("POST", self._path("/extend"), body={"minutes": minutes} if minutes else {})
+        self.session = answer["session"]
+        self.stop_notice = answer.get("stop_notice")
+        return self
+
+    async def stop(self) -> AsyncPhone:
+        """Stops the phone: its apps and data go with it, its workspace stays for the next phone, its replay is saved."""
+        self.session = (await self._client.request("DELETE", self._path()))["session"]
+        return self
+
+
+class AsyncLabels:
+    def __init__(self, client: AsyncNoMac) -> None:
+        self._client = client
+
+    async def delete(self, label: str) -> dict[str, Any]:
+        """
+        Deletes what NoMac keeps for one label, when your user deletes their account: its saved states, its phones'
+        replays and file copies, and its workspace. Answers {"label", "deleted": {"states", "workspaces", "replays",
+        "files"}}; a repeat finds nothing left. The account's key only. Refused while a phone with the label runs
+        (label_in_use) or for 15 minutes after the last one ends (label_busy, details["retry_after_seconds"]).
+        """
+        return await self._client.request("DELETE", f"{LABELS}/{quote(label, safe='')}")
+
+
+class AsyncWebhooks:
+    def __init__(self, client: AsyncNoMac) -> None:
+        self._client = client
+
+    async def create(self, url: str, *, events: builtins.list[str] | None = None) -> dict[str, Any]:
+        """
+        A webhook: each phone's phone.ready and phone.ended POSTed to an https URL, signed. The answer carries its
+        secret, shown once: check each delivery with verify_webhook. Retried with backoff until answered 2xx.
+        """
+        return await self._client.request("POST", WEBHOOKS, body={"url": url, **({"events": events} if events else {})})
+
+    async def list(self) -> builtins.list[dict[str, Any]]:
+        return _base.rows(await self._client.request("GET", WEBHOOKS), "webhooks")
+
+    async def delete(self, id: str) -> dict[str, Any]:
+        """Ends a webhook: nothing more is sent to it."""
+        return await self._client.request("DELETE", f"{WEBHOOKS}/{quote(id, safe='')}")
+
+    async def deliveries(self, id: str, *, limit: int | None = None) -> builtins.list[dict[str, Any]]:
+        """A webhook's deliveries, newest first, kept 30 days: delivered, retrying or gave_up after 12 tries."""
+        return _base.rows(await self._client.request("GET", f"{WEBHOOKS}/{quote(id, safe='')}/deliveries{f'?limit={limit}' if limit else ''}"), "deliveries")