invilabs 0.1.0__tar.gz

invilabs-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include PUBLIC_README.md
+exclude README.md RELEASE_CHECKLIST.md PHOTO_VERIFICATION.md
+prune examples
+prune tools
+prune tests
+global-exclude __pycache__ *.pyc .DS_Store
+recursive-include src/invilabs *.pyi py.typed response_schemas.json

invilabs-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: invilabs
+Version: 0.1.0
+Summary: Blocking Python SDK for Invi Labs phone automation
+Author: Invi Labs
+Project-URL: Homepage, https://invilabs.io
+Project-URL: Documentation, https://sdk.invilabs.io
+Project-URL: Changelog, https://sdk.invilabs.io/downloads/
+Keywords: iphone,automation,sdk,ai-agent,ocr
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Invi Labs Python SDK
+
+Automate real iPhones through the Invi Labs API using your API key and phone ID.
+Non-jailbroken iPhones require [Invi Dongle](https://invilabs.io/connect).
+
+## Install
+
+```sh
+python -m pip install invilabs
+```
+
+Requires Python 3.10 or newer. No third-party runtime dependencies.
+
+## Connect and run an action
+
+Set `INVI_API_KEY` and `INVI_PHONE_ID` in your environment. Keep your API key private.
+
+```python
+import os
+from invilabs import Client
+
+client = Client(os.environ["INVI_API_KEY"])
+phone = client.phone(os.environ["INVI_PHONE_ID"])
+
+print(phone.details())
+phone.tap(100, 200)
+phone.save_screenshot("screen.png")
+```
+
+Coordinates use full-resolution screenshot pixels. Calls block until completion;
+the SDK waits and retries when the phone reports `device_busy`. Uncertain execution
+is not automatically repeated. Use the operation key to look up its status.
+
+## AI generation
+
+```python
+result = client.generate(
+    "Generate an email address using example.com",
+    result_type="email",
+)
+print(result["data"]["text"])
+print(client.balance())
+```
+
+Generation supports text, usernames and email address strings, optionally using a
+local PNG/JPEG image. It does not create mailboxes. OCR, AI prompts and generation
+use your shared Account AI balance. No AI-provider key is required.
+
+## Features
+
+- Tap, swipe, scroll, type, explicit key presses and opening installed apps.
+- Screenshots as PNG bytes or saved to your computer.
+- Grouped OCR with text and bounding boxes.
+- Single-action AI prompts and structured screen answers.
+- Image/video import through Invi Helper on supported dongle phones.
+- Device details, balance and operation recovery.
+
+All network operations use the public HTTPS API with your API key. The package
+contains client code and response contracts; phone control and AI processing run
+on Invi Labs services. API keys remain on your computer and are sent only as an
+authentication header to the configured API. HTTP redirects are not followed.
+
+This is an initial release. Device support and feature verification limits are
+listed in the [release notes](https://sdk.invilabs.io/downloads/).
+
+[Documentation](https://sdk.invilabs.io/) ·
+[Quickstart](https://sdk.invilabs.io/quickstart/) ·
+[Generation and outputs](https://sdk.invilabs.io/reference/generation/) ·
+[Errors and recovery](https://sdk.invilabs.io/reference/credits-and-recovery/)

invilabs-0.1.0/PUBLIC_README.md

@@ -0,0 +1,69 @@
+# Invi Labs Python SDK
+
+Automate real iPhones through the Invi Labs API using your API key and phone ID.
+Non-jailbroken iPhones require [Invi Dongle](https://invilabs.io/connect).
+
+## Install
+
+```sh
+python -m pip install invilabs
+```
+
+Requires Python 3.10 or newer. No third-party runtime dependencies.
+
+## Connect and run an action
+
+Set `INVI_API_KEY` and `INVI_PHONE_ID` in your environment. Keep your API key private.
+
+```python
+import os
+from invilabs import Client
+
+client = Client(os.environ["INVI_API_KEY"])
+phone = client.phone(os.environ["INVI_PHONE_ID"])
+
+print(phone.details())
+phone.tap(100, 200)
+phone.save_screenshot("screen.png")
+```
+
+Coordinates use full-resolution screenshot pixels. Calls block until completion;
+the SDK waits and retries when the phone reports `device_busy`. Uncertain execution
+is not automatically repeated. Use the operation key to look up its status.
+
+## AI generation
+
+```python
+result = client.generate(
+    "Generate an email address using example.com",
+    result_type="email",
+)
+print(result["data"]["text"])
+print(client.balance())
+```
+
+Generation supports text, usernames and email address strings, optionally using a
+local PNG/JPEG image. It does not create mailboxes. OCR, AI prompts and generation
+use your shared Account AI balance. No AI-provider key is required.
+
+## Features
+
+- Tap, swipe, scroll, type, explicit key presses and opening installed apps.
+- Screenshots as PNG bytes or saved to your computer.
+- Grouped OCR with text and bounding boxes.
+- Single-action AI prompts and structured screen answers.
+- Image/video import through Invi Helper on supported dongle phones.
+- Device details, balance and operation recovery.
+
+All network operations use the public HTTPS API with your API key. The package
+contains client code and response contracts; phone control and AI processing run
+on Invi Labs services. API keys remain on your computer and are sent only as an
+authentication header to the configured API. HTTP redirects are not followed.
+
+This is an initial release. Device support and feature verification limits are
+listed in the [release notes](https://sdk.invilabs.io/downloads/).
+
+[Documentation](https://sdk.invilabs.io/) ·
+[Quickstart](https://sdk.invilabs.io/quickstart/) ·
+[Generation and outputs](https://sdk.invilabs.io/reference/generation/) ·
+[Errors and recovery](https://sdk.invilabs.io/reference/credits-and-recovery/)

invilabs-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "invilabs"
+version = "0.1.0"
+description = "Blocking Python SDK for Invi Labs phone automation"
+readme = "PUBLIC_README.md"
+authors = [{name = "Invi Labs"}]
+keywords = ["iphone", "automation", "sdk", "ai-agent", "ocr"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+  "Operating System :: OS Independent",
+]
+requires-python = ">=3.10"
+
+[project.urls]
+Homepage = "https://invilabs.io"
+Documentation = "https://sdk.invilabs.io"
+Changelog = "https://sdk.invilabs.io/downloads/"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+invilabs = ["response_schemas.json", "*.pyi", "py.typed"]

invilabs-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

invilabs-0.1.0/src/invilabs/__init__.py

@@ -0,0 +1,8 @@
+from .client import Client, Phone
+from .errors import (InviError, DeviceBusyError, DeviceOfflineError,
+    InsufficientCreditsError, TargetNotFoundError, InvalidArgumentError,
+    ExecutionUncertainError, OperationInProgressError, IdempotencyConflictError,
+    IdempotencyExpiredError, AuthenticationError, PermissionDeniedError,
+    OperationNotSupportedError, AppNotFoundError, AmbiguousAppError, ScreenshotUnavailableError, ScreenChangedError, OrientationNotSupportedError, BillingPendingError, OCRUnavailableError, ResponseValidationError, MultiStepRequestError, UnsupportedPromptError, PromptUnavailableError, GenerationUnavailableError)
+
+__all__ = ['Client', 'Phone', 'InviError', 'DeviceBusyError', 'DeviceOfflineError', 'InsufficientCreditsError', 'TargetNotFoundError', 'InvalidArgumentError', 'ExecutionUncertainError', 'OperationInProgressError', 'IdempotencyConflictError', 'IdempotencyExpiredError', 'AuthenticationError', 'PermissionDeniedError', 'OperationNotSupportedError', 'AppNotFoundError', 'AmbiguousAppError', 'ScreenshotUnavailableError', 'ScreenChangedError', 'OrientationNotSupportedError', 'BillingPendingError', 'OCRUnavailableError', 'ResponseValidationError', 'MultiStepRequestError', 'UnsupportedPromptError', 'PromptUnavailableError', 'GenerationUnavailableError']

invilabs-0.1.0/src/invilabs/client.py

@@ -0,0 +1,310 @@
+"""Blocking transport. Public device methods are added with their backend milestones."""
+import base64
+import binascii
+import os
+from pathlib import Path
+import struct
+import tempfile
+import json
+import math
+import socket
+import time
+import uuid
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, urlsplit
+from urllib.request import Request, build_opener, HTTPRedirectHandler
+
+from .errors import (ERRORS, InviError, AuthenticationError, PermissionDeniedError,
+                     DeviceBusyError, ExecutionUncertainError)
+
+class _NoRedirect(HTTPRedirectHandler):
+    # Never forward an API key to a redirect target, or turn POST into GET.
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+class _HTTPTransport:
+    def __init__(self):
+        self.opener = build_opener(_NoRedirect())
+
+    def request(self, method, url, headers, body, timeout):
+        req = Request(url, data=body, headers=headers, method=method)
+        try:
+            with self.opener.open(req, timeout=timeout) as response:
+                return response.status, response.read()
+        except HTTPError as error:
+            return error.code, error.read()
+
+class Client:
+    def __init__(self, api_key, *, base_url="https://api.invilabs.io",
+                 busy_timeout=60.0, request_timeout=70.0, _transport=None,
+                 _sleep=time.sleep, _monotonic=time.monotonic, _time=time.time):
+        if not isinstance(api_key, str) or not api_key.strip():
+            raise ValueError("api_key is required")
+        parts = urlsplit(base_url)
+        if parts.scheme != "https" and not (parts.scheme == "http" and parts.hostname in ("localhost", "127.0.0.1", "::1")):
+            raise ValueError("base_url must use HTTPS (HTTP allowed only for localhost)")
+        if not parts.hostname or parts.username or parts.password or parts.query or parts.fragment:
+            raise ValueError("invalid base_url")
+        if busy_timeout is not None and (not math.isfinite(busy_timeout) or busy_timeout < 0):
+            raise ValueError("busy_timeout must be non-negative or None for unlimited")
+        if not math.isfinite(request_timeout) or request_timeout <= 0:
+            raise ValueError("request_timeout must be positive")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._busy_timeout = busy_timeout
+        self._request_timeout = request_timeout
+        self._transport = _transport or _HTTPTransport()
+        self._sleep, self._monotonic, self._time = _sleep, _monotonic, _time
+
+    def balance(self):
+        """Return remaining shared Account AI credits (a snapshot)."""
+        return self._request("GET", "/v1/sdk/balance")["balance_remaining"]
+
+    def generate(self, prompt, *, result_type="text", length=None, image=None):
+        """Answer or generate text, optionally using an uploaded PNG/JPEG.
+
+        No phone required. Optional length is an exact Unicode character count.
+        A new call requests a new variation; usernames are not guaranteed unique.
+        """
+        from .errors import InvalidArgumentError
+        if not isinstance(prompt, str) or not prompt.strip() or any(0xD800 <= ord(c) <= 0xDFFF for c in prompt) or len(prompt.encode("utf-8")) > 4096:
+            raise InvalidArgumentError("prompt must contain 1–4096 UTF-8 bytes", code="invalid_argument")
+        if result_type not in ("text", "username", "email"):
+            raise InvalidArgumentError("result_type must be text, username, or email", code="invalid_argument")
+        maximum = {"username": 64, "email": 254}.get(result_type, 4000)
+        minimum = 5 if result_type == "email" else 1
+        if length is not None and (type(length) is not int or not minimum <= length <= maximum):
+            raise InvalidArgumentError(f"length must be an integer from {minimum} to {maximum}", code="invalid_argument")
+        payload = {"prompt": prompt, "result_type": result_type}
+        if length is not None:
+            payload["length"] = length
+        if image is not None:
+            if isinstance(image, bytes):
+                data = image
+            elif isinstance(image, (str, os.PathLike)):
+                if isinstance(image, str) and image.startswith(("https://", "http://", "data:")):
+                    raise InvalidArgumentError("image must be a local file or bytes, not a URL", code="invalid_argument")
+                with Path(image).open("rb") as source:
+                    data = source.read((5 << 20) + 1)
+            else:
+                raise InvalidArgumentError("image must be a local file path or bytes", code="invalid_argument")
+            if not data or len(data) > 5 << 20 or not (data.startswith(b"\x89PNG\r\n\x1a\n") or data.startswith(b"\xff\xd8\xff")):
+                raise InvalidArgumentError("image must be a PNG/JPEG of at most 5 MiB", code="invalid_argument")
+            payload["image_base64"] = base64.b64encode(data).decode("ascii")
+        return self._request("POST", "/v1/sdk/generate", payload, idempotent=True)
+
+    def operation(self, key):
+        """Look up account-only generation without generating or charging again."""
+        return self._request("GET", f"/v1/sdk/operations?key={quote(key, safe='')}")
+
+    def devices(self):
+        """List phones accessible to this API key. Use phone.details() for status."""
+        return self._request("GET", "/v1/sdk/devices")["devices"]
+
+    def phone(self, phone_id):
+        return Phone(self, str(uuid.UUID(str(phone_id))))
+
+    def _request(self, method, path, payload=None, *, idempotent=False, timeout=None):
+        body = None if payload is None else json.dumps(payload, sort_keys=True, separators=(",", ":"), allow_nan=False).encode()
+        headers = {"Authorization": "Bearer " + self._api_key, "Accept": "application/json", "User-Agent": "invilabs-python/0.1.0"}
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        created = self._time()
+        if idempotent:
+            headers["Idempotency-Key"] = f"{int(created)}.{uuid.uuid4()}"
+        started = self._monotonic()
+        delay = 0.25
+        while True:
+            if idempotent and self._time() - created >= 86400:
+                from .errors import IdempotencyExpiredError
+                raise IdempotencyExpiredError("Operation key expired; request was not resent", code="idempotency_expired")
+            try:
+                status, raw = self._transport.request(method, self._base_url + path, headers.copy(), body, self._request_timeout if timeout is None else timeout)
+            except (URLError, OSError, socket.timeout) as exc:
+                # A transport failure does not establish whether input executed.
+                err = ExecutionUncertainError("Response unavailable; operation was not repeated", code="execution_uncertain")
+                err.idempotency_key = headers.get("Idempotency-Key")
+                raise err from exc
+            try:
+                result = json.loads(raw)
+            except (ValueError, TypeError) as exc:
+                err = ExecutionUncertainError("Invalid response; operation was not repeated", code="execution_uncertain")
+                err.idempotency_key = headers.get("Idempotency-Key")
+                raise err from exc
+            from .contracts import validate_response
+            validate_response(method, path, payload, result, status, headers.get("Idempotency-Key"))
+            if 200 <= status < 300:
+                return result
+            if not isinstance(result, dict):
+                raise InviError("Invalid error response", status=status)
+            code = result.get("error", "http_error")
+            if code == "device_busy":
+                elapsed = self._monotonic() - started
+                remaining = None if self._busy_timeout is None else self._busy_timeout - elapsed
+                if remaining is None or remaining > 0:
+                    self._sleep(delay if remaining is None else min(delay, remaining))
+                    if remaining is not None and self._monotonic() - started >= self._busy_timeout:
+                        raise DeviceBusyError("Phone remained busy until wait timeout", code=code, status=status)
+                    delay = min(delay * 2, 2.0)
+                    continue
+            cls = ERRORS.get(code, AuthenticationError if status == 401 else PermissionDeniedError if status == 403 else InviError)
+            details = dict(result.get("details") or {})
+            for field in ("credits_charged", "balance_remaining"):
+                if field in result:
+                    details[field] = result[field]
+            error = cls(result.get("message", code), code=code, status=status, details=details)
+            error.idempotency_key = headers.get("Idempotency-Key")
+            raise error
+
+class Phone:
+    def __init__(self, client, phone_id):
+        self._client = client
+        self.id = phone_id
+
+    def upload_media(self, path):
+        """Save PNG/JPEG or MP4/MOV through Helper, then delete the Library copy.
+
+        Images: 10 MiB / 40 MP. H.264/HEVC video: 40 MiB. Dongle phones only.
+        Requires device.control and device.upload. A cleanup_failed result means
+        the phone saved the media; do not import it again. No AI credit debit.
+        """
+        from .errors import InvalidArgumentError
+        source = Path(path)
+        ext = source.suffix.lower()
+        if ext not in (".png", ".jpg", ".jpeg", ".mp4", ".mov"):
+            raise InvalidArgumentError("media must be PNG/JPEG or MP4/MOV", code="invalid_argument")
+        limit = (40 if ext in (".mp4", ".mov") else 10) * 1024 * 1024
+        with source.open("rb") as handle:
+            data = handle.read(limit + 1)
+        if not data or len(data) > limit:
+            raise InvalidArgumentError("media exceeds size limit (images 10 MiB; videos 40 MiB)", code="invalid_argument")
+        return self._client._request(
+            "POST", f"/v1/sdk/devices/{self.id}/operations/upload_media",
+            {"filename": source.name, "media_base64": base64.b64encode(data).decode("ascii")},
+            idempotent=True, timeout=max(170.0, self._client._request_timeout))
+
+    def prompt(self, prompt, *, result_type="action"):
+        """One action, or read-only target/answer using fixed SDK-owned schemas.
+
+        Be specific about visible text and screen location. Target and answer
+        never send input. No custom schema, navigation, or action repetition.
+        """
+        from .errors import InvalidArgumentError
+        if not isinstance(prompt, str) or not prompt.strip() or any(0xD800 <= ord(c) <= 0xDFFF for c in prompt) or len(prompt.encode("utf-8")) > 4096:
+            raise InvalidArgumentError("prompt must contain 1–4096 UTF-8 bytes", code="invalid_argument")
+        if result_type not in ("action", "target", "answer"):
+            raise InvalidArgumentError("result_type must be action, target, or answer", code="invalid_argument")
+        return self._operation("prompt", {"prompt": prompt, "result_type": result_type})
+
+    def ocr(self):
+        """Full-screen grouped text and PNG-pixel boxes, plus charge and balance."""
+        return self._operation("ocr", {})
+
+    def details(self):
+        """Read online/busy state and screenshot-pixel dimensions (screen may be None)."""
+        return self._client._request("GET", f"/v1/sdk/devices/{self.id}")
+
+    def screenshot(self):
+        """Return a fresh full-screen PNG as bytes, in the same pixels as tap/swipe.
+
+        Busy waits reuse one request key. A replay of an existing operation
+        returns its original image; a new screenshot() call captures again.
+        """
+        from .errors import ScreenshotUnavailableError
+        result = self._operation("screenshot", {})
+        try:
+            data = base64.b64decode(result["image_base64"], validate=True)
+            width, height = struct.unpack(">II", data[16:24])
+            if (result["format"] != "png" or data[:8] != b"\x89PNG\r\n\x1a\n"
+                    or data[8:16] != b"\x00\x00\x00\rIHDR"
+                    or data[-12:] != b"\x00\x00\x00\x00IEND\xaeB`\x82" or width < 2 or height < 2
+                    or width != result["width"] or height != result["height"]):
+                raise ValueError("invalid PNG dimensions")
+        except (KeyError, TypeError, ValueError, binascii.Error, struct.error) as exc:
+            raise ScreenshotUnavailableError("Invalid screenshot response", code="screenshot_unavailable") from exc
+        return data
+
+    def save_screenshot(self, path):
+        """Capture and atomically save PNG to path; return Path. Local errors raise OSError.
+
+        Existing files are replaced only after the complete PNG has been written.
+        Parent directories must exist. No second capture on a local write error.
+        """
+        target = Path(path)
+        temporary = None
+        try:
+            with tempfile.NamedTemporaryFile(dir=target.parent, prefix=".invilabs-", suffix=".png", delete=False) as f:
+                temporary = Path(f.name)
+                f.write(self.screenshot())
+                f.flush()
+                os.fsync(f.fileno())
+            os.replace(temporary, target)
+            return target
+        finally:
+            if temporary is not None:
+                temporary.unlink(missing_ok=True)
+
+    def tap(self, x, y):
+        """Tap once in native screen pixels; wait for execution acknowledgment."""
+        if isinstance(x, bool) or isinstance(y, bool) or not isinstance(x, int) or not isinstance(y, int) or x < 0 or y < 0:
+            from .errors import InvalidArgumentError
+            raise InvalidArgumentError("x and y must be non-negative integers", code="invalid_argument")
+        return self._operation("tap", {"x": x, "y": y})
+
+    @staticmethod
+    def _integer(value, name, minimum=0, maximum=None):
+        if isinstance(value, bool) or not isinstance(value, int) or value < minimum or (maximum is not None and value > maximum):
+            from .errors import InvalidArgumentError
+            raise InvalidArgumentError(f"Invalid {name}", code="invalid_argument")
+
+    def swipe(self, x1, y1, x2, y2, *, duration_ms=500):
+        """One swipe between native-pixel endpoints; duration 1–5000 ms."""
+        for name, value in (("x1",x1),("y1",y1),("x2",x2),("y2",y2)):
+            self._integer(value, name)
+        self._integer(duration_ms, "duration_ms", 1, 5000)
+        return self._operation("swipe", dict(x1=x1,y1=y1,x2=x2,y2=y2,duration_ms=duration_ms))
+
+    def scroll(self, direction, *, distance=None, duration_ms=500):
+        """One gesture: down moves the finger upward; up moves it downward.
+
+        Distance is native pixels (default 60% of screen height), not the
+        resulting distance the content moves.
+        """
+        from .errors import InvalidArgumentError
+        if direction not in ("up", "down"):
+            raise InvalidArgumentError("direction must be up or down", code="invalid_argument")
+        self._integer(duration_ms, "duration_ms", 1, 5000)
+        args = dict(direction=direction,duration_ms=duration_ms)
+        if distance is not None:
+            self._integer(distance,"distance",1)
+            args["distance"] = distance
+        return self._operation("scroll",args)
+
+    def type(self, text):
+        """Insert text without clearing or submitting. Use press('enter') explicitly."""
+        from .errors import InvalidArgumentError
+        import unicodedata
+        if not isinstance(text,str) or not text or any(unicodedata.category(c) in ("Cc", "Cs") for c in text) or len(text.encode("utf-8")) > 1024:
+            raise InvalidArgumentError("text must be 1–1024 UTF-8 bytes without control characters",code="invalid_argument")
+        return self._operation("type",{"text":text})
+
+    def press(self, key):
+        """Press enter, backspace, home, or app_switcher."""
+        from .errors import InvalidArgumentError
+        if key not in ("enter","backspace","home","app_switcher"):
+            raise InvalidArgumentError("unsupported key",code="invalid_argument")
+        return self._operation("press",{"key":key})
+
+    def open_app(self, app):
+        """Open an installed app by name or bundle ID; never installs an app."""
+        from .errors import InvalidArgumentError
+        if not isinstance(app,str) or not app.strip() or any(ord(c)<32 or 127<=ord(c)<=159 or 0xD800<=ord(c)<=0xDFFF for c in app) or len(app.encode("utf-8")) > 255:
+            raise InvalidArgumentError("app name or bundle ID required",code="invalid_argument")
+        return self._operation("open_app",{"app":app.strip()})
+
+    def operation(self, key):
+        """Read a prior operation's status without repeating its device action."""
+        return self._client._request("GET", f"/v1/sdk/devices/{self.id}/operations?key={quote(key, safe='')}")
+
+    def _operation(self, name, payload):
+        return self._client._request("POST", f"/v1/sdk/devices/{self.id}/operations/{quote(name, safe='')}", payload, idempotent=True)

invilabs-0.1.0/src/invilabs/client.pyi

@@ -0,0 +1,36 @@
+from os import PathLike
+from pathlib import Path
+from typing import Literal, overload
+from .types import (DeviceDetails, DevicesResultDevicesItem, TapResult, SwipeResult,
+    ScrollResult, TypeResult, PressResult, OpenAppResult, OcrResult, PromptActionResult,
+    PromptTargetResult, PromptAnswerResult, OperationResult, UploadMediaResult, GenerateResult)
+
+class Client:
+    def __init__(self, api_key: str, *, base_url: str = ..., busy_timeout: float | None = ..., request_timeout: float = ...) -> None: ...
+    def balance(self) -> float: ...
+    def generate(self, prompt: str, *, result_type: Literal['text', 'username', 'email'] = ..., length: int | None = ..., image: str | PathLike[str] | bytes | None = ...) -> GenerateResult: ...
+    def operation(self, key: str) -> OperationResult: ...
+    def devices(self) -> list[DevicesResultDevicesItem]: ...
+    def phone(self, phone_id: str) -> Phone: ...
+
+class Phone:
+    id: str
+    def __init__(self, client: Client, phone_id: str) -> None: ...
+    def details(self) -> DeviceDetails: ...
+    def tap(self, x: int, y: int) -> TapResult: ...
+    def swipe(self, x1: int, y1: int, x2: int, y2: int, *, duration_ms: int = ...) -> SwipeResult: ...
+    def scroll(self, direction: Literal['up', 'down'], *, distance: int | None = ..., duration_ms: int = ...) -> ScrollResult: ...
+    def type(self, text: str) -> TypeResult: ...
+    def press(self, key: Literal['enter', 'backspace', 'home', 'app_switcher']) -> PressResult: ...
+    def open_app(self, app: str) -> OpenAppResult: ...
+    def screenshot(self) -> bytes: ...
+    def save_screenshot(self, path: str | PathLike[str]) -> Path: ...
+    def ocr(self) -> OcrResult: ...
+    @overload
+    def prompt(self, prompt: str, *, result_type: Literal['action'] = ...) -> PromptActionResult: ...
+    @overload
+    def prompt(self, prompt: str, *, result_type: Literal['target']) -> PromptTargetResult: ...
+    @overload
+    def prompt(self, prompt: str, *, result_type: Literal['answer']) -> PromptAnswerResult: ...
+    def operation(self, key: str) -> OperationResult: ...
+    def upload_media(self, path: str | PathLike[str]) -> UploadMediaResult: ...

invilabs-0.1.0/src/invilabs/contracts.py

@@ -0,0 +1,71 @@
+"""SDK-owned v1 wire contracts. Invalid responses never cause a resend."""
+import json
+import math
+import re
+from importlib.resources import files
+from .errors import ResponseValidationError
+
+EMAIL = re.compile('^[A-Za-z0-9_%+-]+(?:\\.[A-Za-z0-9_%+-]+)*@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$')
+
+def _valid_email(value):
+    return len(value) <= 254 and value.find('@') <= 64 and EMAIL.fullmatch(value) is not None
+
+SCHEMAS = json.loads(files('invilabs').joinpath('response_schemas.json').read_text())['schemas']
+
+def _matches(value, schema):
+    if 'anyOf' in schema:
+        return any(_matches(value, candidate) for candidate in schema['anyOf'])
+    kind = schema.get('type')
+    if kind == 'object':
+        if not isinstance(value, dict): return False
+        props = schema.get('properties', {})
+        if not all(key in value for key in schema.get('required', [])): return False
+        if schema.get('additionalProperties') is False and set(value) - set(props): return False
+        return all(_matches(value[key], spec) for key, spec in props.items() if key in value)
+    if kind == 'array':
+        return isinstance(value, list) and all(_matches(item, schema['items']) for item in value)
+    if kind == 'string': valid = isinstance(value, str)
+    elif kind == 'boolean': valid = isinstance(value, bool)
+    elif kind == 'null': valid = value is None
+    elif kind == 'integer': valid = type(value) is int
+    elif kind == 'number': valid = type(value) in (int, float) and math.isfinite(value)
+    else: return False
+    if not valid: return False
+    if 'minimum' in schema and value < schema['minimum']: return False
+    if 'maximum' in schema and value > schema['maximum']: return False
+    if 'minLength' in schema and len(value) < schema['minLength']: return False
+    if 'maxLength' in schema and len(value) > schema['maxLength']: return False
+    return 'enum' not in schema or value in schema['enum']
+
+def validate_response(method, path, payload, result, status, key):
+    if status >= 400:
+        name = 'error'
+    elif '/operations?' in path: name = 'operation'
+    elif '/operations/' in path:
+        name = path.rsplit('/', 1)[-1]
+        if name == 'prompt': name += '_' + (payload or {}).get('result_type', 'action')
+    elif path.endswith('/generate'): name = 'generate'
+    elif path.endswith('/balance'): name = 'balance'
+    elif path.endswith('/devices'): name = 'devices'
+    else: name = 'details'
+    valid = name in SCHEMAS and _matches(result, SCHEMAS[name])
+    generated = result.get('result') if valid and name == 'operation' else result
+    if valid and isinstance(generated, dict) and generated.get('operation') == 'generate':
+        data, mode = generated['data'], generated['result_type']
+        text = data['text']
+        valid = bool(text.strip()) and data['length'] == len(text) and not any(0xD800 <= ord(c) <= 0xDFFF for c in text)
+        if mode == 'username': valid = valid and len(text) <= 64 and re.fullmatch(r'[A-Za-z0-9_]+', text) is not None
+        if mode == 'email': valid = valid and _valid_email(text)
+        if name == 'generate':
+            valid = valid and mode == (payload or {}).get('result_type', 'text')
+            expected = (payload or {}).get('length')
+            if expected is not None: valid = valid and len(text) == expected
+    if not valid:
+        details = {}
+        if isinstance(result, dict):
+            details = {k: result[k] for k in ('credits_charged', 'balance_remaining')
+                       if k in result and _matches(result[k], {'type':'number','minimum':0})}
+        error = ResponseValidationError('Response violates the SDK v1 contract; request was not repeated', code='response_validation_failed', status=status, details=details)
+        error.idempotency_key = key
+        raise error
+    return result