nomac 0.1.0__py3-none-any.whl

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/_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")

nomac/_base.py

@@ -0,0 +1,210 @@
+"""What the sync and async clients share: NoMac's answers read the same way, and webhooks checked the same way."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import re
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+DEFAULT_BASE_URL = "https://nomac.app"
+SESSIONS = "/api/v1/simulator/sessions"
+WEBHOOKS = "/api/v1/simulator/webhooks"
+LABELS = "/api/v1/simulator/labels"
+# Statuses that pass: NoMac or the phone busy for a moment. A 429 was not taken, so any request may be sent again.
+PASSING = {429, 502, 503, 504}
+ENDED = {"stopping", "stopped", "failed"}
+JOB = re.compile(r'Next: job_status \{job_id: "([^"]+)"\}')
+# job_status's answer while the job still runs: read it again with the same job.
+STILL_RUNNING = re.compile(r"\nNext: job_status again, or job_cancel\.")
+ATTEMPTS = 4
+
+
+class NoMacError(Exception):
+    """NoMac's refusal, in its own words: code (stable, for code to branch on), message (for a person), status."""
+
+    def __init__(self, code: str, message: str, status: int = 0, details: Any = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+        self.details = details
+
+    def __repr__(self) -> str:
+        return f"NoMacError(code={self.code!r}, status={self.status}, message={self.message!r})"
+
+
+@dataclass
+class ToolResult:
+    """A tool's result: text says what happened and what to do next; content has its text and images."""
+
+    text: str
+    content: list[dict[str, Any]]
+    is_error: bool
+    notices: list[str] = field(default_factory=list)
+    stop_notice: dict[str, Any] | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+def request_key(prefix: str = "sdk") -> str:
+    """A request key: the same key makes a retry the same request (a start, a tool call, a fetch)."""
+    return f"{prefix}-{uuid.uuid4()}"
+
+
+def credential(api_key: str | None, token: str | None) -> str:
+    value = api_key or token or os.environ.get("NOMAC_API_KEY")
+    if not value:
+        raise NoMacError("credential_required", "Pass api_key (the account's nmk_ key) or token (one phone's nmp_ token), or set NOMAC_API_KEY.")
+    return value
+
+
+def headers(auth: str, idempotency_key: str | None, has_body: bool) -> dict[str, str]:
+    out = {"authorization": auth}
+    if idempotency_key:
+        out["idempotency-key"] = idempotency_key
+    if has_body:
+        out["content-type"] = "application/json"
+    return out
+
+
+def repeatable(method: str, idempotency_key: str | None) -> bool:
+    """A read, a stop and a request with a key may be sent again; anything else only when NoMac answered 429."""
+    return method in ("GET", "DELETE") or bool(idempotency_key)
+
+
+def pause_seconds(attempt: int, retry_after: str | None = None) -> float:
+    try:
+        after = float(retry_after) if retry_after is not None else 0.0
+    except ValueError:
+        after = 0.0
+    return min(after, 30.0) if after > 0 else attempt * 2.0
+
+
+def answer(method: str, path: str, attempt: int, again: bool, status: int, text: str, retry_after: str | None) -> dict[str, Any] | float:
+    """What to do with NoMac's answer: its payload once done, the seconds to wait before asking again, or a NoMacError."""
+    try:
+        parsed = json.loads(text) if text else {}
+    except ValueError:
+        parsed = {}
+    payload: dict[str, Any] = parsed if isinstance(parsed, dict) else {}
+    if 200 <= status < 300:
+        return payload
+    # A repeated DELETE whose first try was taken (its answer lost on the way) finds nothing left to delete.
+    if method == "DELETE" and path.startswith(WEBHOOKS) and attempt > 1 and status == 404:
+        return {"deleted": True}
+    if status in PASSING and (again or status == 429) and attempt < ATTEMPTS:
+        return pause_seconds(attempt, retry_after)
+    raw = payload.get("error")
+    error: dict[str, Any] = raw if isinstance(raw, dict) else {}
+    raise NoMacError(error.get("code") or f"http_{status}", error.get("message") or f"NoMac answered {status}.", status, error)
+
+
+def rows(payload: dict[str, Any], key: str) -> list[dict[str, Any]]:
+    """The list an answer holds under key (sessions, webhooks, deliveries, states)."""
+    value = payload.get(key)
+    return value if isinstance(value, list) else []
+
+
+def unreachable(error: Exception) -> NoMacError:
+    return NoMacError("unreachable", f"NoMac did not answer ({error}).")
+
+
+def tool_result(name: str, answer: dict[str, Any]) -> ToolResult:
+    """A call's final answer as a ToolResult: cancelled, failed without a result, or its content."""
+    stop_notice = answer.get("stop_notice")
+    if answer.get("state") == "cancelled":
+        return ToolResult(f"{name} was cancelled.", [], True, [], stop_notice, answer)
+    result = answer.get("result")
+    if not isinstance(result, dict):
+        reason = answer.get("message") or answer.get("error") or answer.get("state")
+        raise NoMacError(answer.get("error") or "tool_failed", f"{name} failed on the phone: {reason}.", 0, answer)
+    content = result.get("content") or []
+    text = "\n".join(c.get("text") or "" for c in content if c.get("type") == "text")
+    raw = answer.get("notices")
+    notices = [str(n) for n in raw] if isinstance(raw, list) else []
+    # phone_restarted: the phone's session server came back since the last call (its apps and data are kept).
+    return ToolResult(text, content, bool(result.get("isError")), notices, stop_notice, answer)
+
+
+def job_of(result: ToolResult) -> str | None:
+    found = JOB.search(result.text) if not result.is_error else None
+    return found.group(1) if found else None
+
+
+def operation_answer(answer: dict[str, Any], key: str, by: float) -> bool:
+    """Whether an operation (a fetch, a save) is done; still running past by is a timeout naming its key."""
+    if answer.get("state") == "running":
+        if time.monotonic() >= by:
+            raise NoMacError("timeout", f"The phone was still at it; the same call with idempotency_key {key} reads it later.", 0, answer)
+        return False
+    if answer.get("state") == "failed":
+        raise NoMacError(answer.get("error") or "operation_failed", answer.get("message") or f"The phone could not do it ({answer.get('error') or 'failed'}).", 0, answer)
+    return True
+
+
+def archive_bytes(data: bytes | bytearray | memoryview | str | os.PathLike[str]) -> tuple[bytes | None, str | None, int, str]:
+    """An archive as bytes, or a file's path read in pieces: (bytes, path, size, sha256)."""
+    if isinstance(data, (bytes, bytearray, memoryview)):
+        raw = bytes(data)
+        return raw, None, len(raw), hashlib.sha256(raw).hexdigest()
+    path = os.fspath(data)
+    digest = hashlib.sha256()
+    with open(path, "rb") as file:
+        for piece in iter(lambda: file.read(1 << 20), b""):
+            digest.update(piece)
+    return None, path, os.path.getsize(path), digest.hexdigest()
+
+
+def verify_webhook(body: bytes | str, signature: str | None, secret: str, *, tolerance_seconds: int = 300, now: float | None = None) -> dict[str, Any]:
+    """
+    Checks a webhook delivery and answers its event: body (the raw request body, as received), signature (the
+    nomac-signature header), secret (the webhook's whsec_... secret). Refused when the signature does not match or is
+    older than tolerance_seconds (5 minutes). A delivery can come more than once: key on its id (nomac-delivery).
+    """
+    text = body.decode("utf-8") if isinstance(body, (bytes, bytearray)) else body
+    parts = dict(part.strip().split("=", 1) for part in (signature or "").split(",") if "=" in part)
+    t, v1 = parts.get("t", ""), parts.get("v1", "")
+    if not t.isdigit() or not re.fullmatch(r"[a-f0-9]{64}", v1):
+        raise NoMacError("webhook_signature_invalid", "The nomac-signature header is missing or malformed.")
+    if abs((time.time() if now is None else now) - int(t)) > tolerance_seconds:
+        raise NoMacError("webhook_signature_expired", "The delivery's signature is too old; it may be a replay.")
+    want = hmac.new(secret.encode(), f"{t}.{text}".encode(), hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(want, v1):
+        raise NoMacError("webhook_signature_invalid", "The delivery's signature does not match this webhook's secret.")
+    event = json.loads(text)
+    if not isinstance(event, dict):
+        raise NoMacError("webhook_invalid", "The delivery's body is not a NoMac event.")
+    return event
+
+
+def start_body(device: str | None, label: str | None, reuse: bool | None, limits: Mapping[str, Any] | None) -> dict[str, Any]:
+    body: dict[str, Any] = {}
+    if device is not None:
+        body["device"] = device
+    if label is not None:
+        body["label"] = label
+    if reuse is not None:
+        body["reuse"] = reuse
+    if limits is not None:
+        body["limits"] = dict(limits)
+    return body
+
+
+def tool_arguments(arguments: Mapping[str, Any] | None, more: Mapping[str, Any]) -> dict[str, Any]:
+    return {**(dict(arguments) if arguments else {}), **more}
+
+
+def git_body(url: str, ref: str | None, token: str | None, secret: str | None) -> dict[str, Any]:
+    body: dict[str, Any] = {"url": url}
+    if ref:
+        body["ref"] = ref
+    if token:
+        body["token"] = token
+    if secret:
+        body["secret"] = secret
+    return body

nomac/_sync.py

@@ -0,0 +1,289 @@
+"""The client: NoMac Simulator's phones for a platform's users and agents, over NoMac's REST API."""
+
+from __future__ import annotations
+
+import builtins
+import os
+import time
+from typing import Any, Mapping
+from urllib.parse import quote
+
+import httpx
+
+from . import _base
+from ._base import ENDED, LABELS, SESSIONS, WEBHOOKS, NoMacError, ToolResult, request_key
+
+
+class NoMac:
+    """
+    A client for an account (its API key, nmk_...) or for one phone (the token a platform hands its own user,
+    nmp_...). NOMAC_API_KEY from the environment by default. Close it, or use it in a with block.
+    """
+
+    def __init__(self, api_key: str | None = None, *, token: str | None = None, base_url: str = _base.DEFAULT_BASE_URL,
+                 http_client: httpx.Client | 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.Client(timeout=timeout)
+        self._own_http = http_client is None
+        self.phones = Phones(self)
+        self.labels = Labels(self)
+        self.webhooks = Webhooks(self)
+
+    def phone(self, id: str) -> Phone:
+        """A phone by its id, without reading it (a phone's token reaches its own only)."""
+        return Phone(self, {"id": id})
+
+    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 = 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:
+                    time.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
+            time.sleep(value)
+        raise NoMacError("unreachable", "NoMac did not answer.")
+
+    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 = self._http.put(url, content=data, headers=headers, timeout=30 * 60)
+        else:
+            with open(path, "rb") as file:
+                response = self._http.put(url, content=file, 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)
+
+    def close(self) -> None:
+        if self._own_http:
+            self._http.close()
+
+    def __enter__(self) -> NoMac:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class Phones:
+    def __init__(self, client: NoMac) -> None:
+        self._client = client
+
+    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) -> Phone:
+        """
+        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 = self._client.request("POST", SESSIONS, body=_base.start_body(device, label, reuse, limits), idempotency_key=idempotency_key or request_key("start"))
+        return Phone(self._client, answer["session"], answer.get("links"), bool(answer.get("reused")))
+
+    def list(self, *, label: str | None = None) -> builtins.list[Phone]:
+        """The account's phones, newest first; with label, the ones a platform named so."""
+        answer = self._client.request("GET", f"{SESSIONS}?label={quote(label, safe='')}" if label else SESSIONS)
+        return [Phone(self._client, session) for session in _base.rows(answer, "sessions")]
+
+    def get(self, id: str) -> Phone:
+        return Phone(self._client, {"id": id}).refresh()
+
+
+class Phone:
+    """A phone: its session (state, device, label, cost, deadlines) and links, and what can be done with it."""
+
+    def __init__(self, client: NoMac, 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}"
+
+    def refresh(self) -> Phone:
+        answer = 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
+
+    def wait_until_ready(self, *, timeout: float = 6 * 60, interval: float = 1.0) -> Phone:
+        """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)
+            time.sleep(interval)
+            self.refresh()
+
+    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 = 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 = 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
+
+    def _call(self, name: str, arguments: dict[str, Any], key: str, by: float, interval: float) -> ToolResult:
+        answer = 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)
+            time.sleep(interval)
+            answer = self._client.request("GET", self._path(f"/calls/{answer['id']}"))
+        return _base.tool_result(name, answer)
+
+    def cancel(self, call_id: str) -> dict[str, Any]:
+        """Stops a running tool call; a finished one is answered as it is."""
+        return 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.
+    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 = self._client.request("POST", self._path(path), body=body, idempotency_key=key)
+            if _base.operation_answer(answer, key, by):
+                return answer
+            time.sleep(interval)
+
+    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 self._operation("/sync/git", _base.git_body(url, ref, token, secret), idempotency_key or request_key("git"), timeout)
+
+    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 = self._client.request("POST", self._path("/sync/upload"), body={"size": size, "sha256": sha256})
+        self._client._upload(link["upload_url"], raw, path, size)
+        return self._operation("/sync/fetch", {"sha256": sha256, **({"name": name} if name else {})}, idempotency_key or request_key("upload"), timeout)
+
+    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 self._client.request("POST", self._path("/view"), body={"control": control, **({"minutes": minutes} if minutes else {})})
+
+    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: NoMac(token=...) reaches its tools, files,
+        state and view, until it expires (2 hours by default, a day at most) or the phone ends.
+        """
+        return self._client.request("POST", self._path("/token"), body={"minutes": minutes} if minutes else {})
+
+    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 self._client.request("DELETE", self._path("/token"))
+
+    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 self._client.request("GET", self._path("/replay"))
+
+    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 self._operation("/state", {"action": "save", "name": name}, idempotency_key or request_key("state"), timeout)
+
+    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 self._operation("/state", {"action": "restore", "name": name}, idempotency_key or request_key("state"), timeout)
+
+    def list_states(self) -> builtins.list[dict[str, Any]]:
+        return _base.rows(self._operation("/state", {"action": "list"}, request_key("state"), None), "states")
+
+    def delete_state(self, name: str) -> dict[str, Any]:
+        return self._operation("/state", {"action": "delete", "name": name}, request_key("state"), None)
+
+    def extend(self, *, minutes: int | None = None) -> Phone:
+        """
+        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 = 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
+
+    def stop(self) -> Phone:
+        """Stops the phone: its apps and data go with it, its workspace stays for the next phone, its replay is saved."""
+        self.session = self._client.request("DELETE", self._path())["session"]
+        return self
+
+
+class Labels:
+    def __init__(self, client: NoMac) -> None:
+        self._client = client
+
+    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 self._client.request("DELETE", f"{LABELS}/{quote(label, safe='')}")
+
+
+class Webhooks:
+    def __init__(self, client: NoMac) -> None:
+        self._client = client
+
+    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 self._client.request("POST", WEBHOOKS, body={"url": url, **({"events": events} if events else {})})
+
+    def list(self) -> builtins.list[dict[str, Any]]:
+        return _base.rows(self._client.request("GET", WEBHOOKS), "webhooks")
+
+    def delete(self, id: str) -> dict[str, Any]:
+        """Ends a webhook: nothing more is sent to it."""
+        return self._client.request("DELETE", f"{WEBHOOKS}/{quote(id, safe='')}")
+
+    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(self._client.request("GET", f"{WEBHOOKS}/{quote(id, safe='')}/deliveries{f'?limit={limit}' if limit else ''}"), "deliveries")

nomac-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+nomac/__init__.py,sha256=yiz5sOvq1XC9c1xNBR_Y11FaEiekaLT5H14k8nHywDU,511
+nomac/_async.py,sha256=xpE_6LCdTNl6EXQj7_s0RiB1kXg19EfUK_yY5u2O6dQ,17172
+nomac/_base.py,sha256=8OA-Tme6_Dfi0Arm7iV80T8ILGQXZ1G_jreToymjZac,9354
+nomac/_sync.py,sha256=4fBKBBN-Ul-WtemRi4T5YJl-xcyEhJjvb_UsTwJe5IE,16320
+nomac/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nomac-0.1.0.dist-info/METADATA,sha256=jnItw277fKXxPuUalgW-Whq5kLk7xKkAZduKR_hmTP4,8791
+nomac-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+nomac-0.1.0.dist-info/licenses/LICENSE,sha256=RcExWFfUmukhyhBnMLh2ew6vje3Yv5-LZM1bCy_mGHI,1062
+nomac-0.1.0.dist-info/RECORD,,

nomac-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

nomac-0.1.0.dist-info/licenses/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.