tryorchard-sdk 0.0.1__tar.gz

tryorchard_sdk-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AirOverflow
+
+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.

tryorchard_sdk-0.0.1/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: tryorchard-sdk
+Version: 0.0.1
+Summary: Python client for Orchard: drive iOS and Android sandboxes over REST and live WebSocket channels.
+Author: AirOverflow
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/tryorchard/sdk
+Project-URL: Documentation, https://github.com/tryorchard/sdk/blob/main/python/docs/reference.md
+Project-URL: Source, https://github.com/tryorchard/sdk/tree/main/python
+Project-URL: Issues, https://github.com/tryorchard/sdk/issues
+Keywords: orchard,android,ios,sandbox,emulator,automation,frida
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<0.29,>=0.28
+Requires-Dist: websockets<15,>=14
+Requires-Dist: typing_extensions>=4.7; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# tryorchard-sdk
+
+Python client for [Orchard](https://docs.orchard.airoverflow.com): create and drive iOS and Android sandboxes, manage snapshots, templates, teams and scoped API keys, and stream live channels (logs, shell, screen, adb, VNC, mitm, frida).
+
+```bash
+pip install tryorchard-sdk
+```
+
+Requires Python 3.10+. The import name is `orchard_sdk`.
+
+## Quickstart
+
+```python
+from orchard_sdk import Orchard
+
+orchard = Orchard.from_env()  # ORCHARD_API_URL + ORCHARD_API_KEY
+# or: Orchard("https://orchard.example.com", "orc_live_xxx")
+
+for s in orchard.sandboxes.list()["instances"]:
+    print(s["name"], s["state"])
+
+sb = orchard.sandbox("my-pixel")  # uuid, uuid prefix, name or tag
+sb.start()
+sb.apps.install("./build/app.apk")
+sb.launch("com.example.app")
+sb.tap_text("Sign in")
+
+with open("screen.png", "wb") as f:
+    f.write(sb.screenshot())
+
+with sb.logs() as stream:
+    for line in stream:
+        print(line)
+```
+
+## Configuration
+
+| Variable | Purpose |
+| --- | --- |
+| `ORCHARD_API_URL` | Control-plane URL, e.g. `https://orchard.example.com` |
+| `ORCHARD_API_KEY` | API key (`orc_…`) or JWT access token |
+| `ORCHARD_ORG` | Optional org slug (ignored for API keys) |
+| `ORCHARD_WS` | Optional workspace slug |
+
+Explicit arguments to `Orchard(...)` win over the environment. The client holds a connection pool: use it as a context manager or call `close()`.
+
+## Live channels
+
+Channels are context-managed iterators that work in ordinary synchronous code:
+
+```python
+with sb.shell() as sh:
+    sh.send("getprop ro.build.version.release\n")
+    for out in sh:
+        print(out, end="")
+```
+
+For asyncio code use `orchard_sdk.aio.AsyncChannels`:
+
+```python
+import asyncio
+from orchard_sdk import from_env
+from orchard_sdk.aio import AsyncChannels
+
+async def main():
+    async for line in AsyncChannels(from_env(), sb.uuid).logs():
+        print(line)
+
+asyncio.run(main())
+```
+
+Expose a device channel on a local port for ordinary tools:
+
+```python
+with sb.adb_bridge() as bridge:
+    print(f"adb connect 127.0.0.1:{bridge.port}")
+```
+
+## Errors
+
+All errors derive from `OrchardError`: `ApiError` (HTTP status + server detail), `SelectorError` (zero or ambiguous sandbox match), `ChannelClosedError` (WebSocket closed with 4401/4403/4404/4502).
+
+```python
+from orchard_sdk import ApiError, SelectorError
+
+try:
+    orchard.sandbox("pixel").start()
+except SelectorError as e:
+    print(e)
+except ApiError as e:
+    print(e.status, e.detail)
+```
+
+## Documentation
+
+- [API reference](https://github.com/tryorchard/sdk/blob/main/python/docs/reference.md): every method, with examples
+- [Examples](https://github.com/tryorchard/sdk/tree/main/python/examples): install and launch, UI test with snapshot rollback, frida tracing, traffic capture, adb bridge, scoped keys, log streaming
+
+## License
+
+MIT

tryorchard_sdk-0.0.1/README.md

@@ -0,0 +1,101 @@
+# tryorchard-sdk
+
+Python client for [Orchard](https://docs.orchard.airoverflow.com): create and drive iOS and Android sandboxes, manage snapshots, templates, teams and scoped API keys, and stream live channels (logs, shell, screen, adb, VNC, mitm, frida).
+
+```bash
+pip install tryorchard-sdk
+```
+
+Requires Python 3.10+. The import name is `orchard_sdk`.
+
+## Quickstart
+
+```python
+from orchard_sdk import Orchard
+
+orchard = Orchard.from_env()  # ORCHARD_API_URL + ORCHARD_API_KEY
+# or: Orchard("https://orchard.example.com", "orc_live_xxx")
+
+for s in orchard.sandboxes.list()["instances"]:
+    print(s["name"], s["state"])
+
+sb = orchard.sandbox("my-pixel")  # uuid, uuid prefix, name or tag
+sb.start()
+sb.apps.install("./build/app.apk")
+sb.launch("com.example.app")
+sb.tap_text("Sign in")
+
+with open("screen.png", "wb") as f:
+    f.write(sb.screenshot())
+
+with sb.logs() as stream:
+    for line in stream:
+        print(line)
+```
+
+## Configuration
+
+| Variable | Purpose |
+| --- | --- |
+| `ORCHARD_API_URL` | Control-plane URL, e.g. `https://orchard.example.com` |
+| `ORCHARD_API_KEY` | API key (`orc_…`) or JWT access token |
+| `ORCHARD_ORG` | Optional org slug (ignored for API keys) |
+| `ORCHARD_WS` | Optional workspace slug |
+
+Explicit arguments to `Orchard(...)` win over the environment. The client holds a connection pool: use it as a context manager or call `close()`.
+
+## Live channels
+
+Channels are context-managed iterators that work in ordinary synchronous code:
+
+```python
+with sb.shell() as sh:
+    sh.send("getprop ro.build.version.release\n")
+    for out in sh:
+        print(out, end="")
+```
+
+For asyncio code use `orchard_sdk.aio.AsyncChannels`:
+
+```python
+import asyncio
+from orchard_sdk import from_env
+from orchard_sdk.aio import AsyncChannels
+
+async def main():
+    async for line in AsyncChannels(from_env(), sb.uuid).logs():
+        print(line)
+
+asyncio.run(main())
+```
+
+Expose a device channel on a local port for ordinary tools:
+
+```python
+with sb.adb_bridge() as bridge:
+    print(f"adb connect 127.0.0.1:{bridge.port}")
+```
+
+## Errors
+
+All errors derive from `OrchardError`: `ApiError` (HTTP status + server detail), `SelectorError` (zero or ambiguous sandbox match), `ChannelClosedError` (WebSocket closed with 4401/4403/4404/4502).
+
+```python
+from orchard_sdk import ApiError, SelectorError
+
+try:
+    orchard.sandbox("pixel").start()
+except SelectorError as e:
+    print(e)
+except ApiError as e:
+    print(e.status, e.detail)
+```
+
+## Documentation
+
+- [API reference](https://github.com/tryorchard/sdk/blob/main/python/docs/reference.md): every method, with examples
+- [Examples](https://github.com/tryorchard/sdk/tree/main/python/examples): install and launch, UI test with snapshot rollback, frida tracing, traffic capture, adb bridge, scoped keys, log streaming
+
+## License
+
+MIT

tryorchard_sdk-0.0.1/orchard_sdk/__init__.py

@@ -0,0 +1,37 @@
+"""Orchard SDK — a Python client for the Orchard mobile-sandbox control plane.
+
+Quickstart::
+
+    from orchard_sdk import Orchard
+
+    orchard = Orchard.from_env()            # ORCHARD_API_URL + ORCHARD_API_KEY
+    for s in orchard.sandboxes.list()["instances"]:
+        print(s["name"], s["state"])
+
+    sb = orchard.sandbox("my-pixel")        # by uuid / uuid-prefix / name / tag
+    sb.tag("payments", "#22c55e")
+    with sb.logs() as stream:
+        for line in stream:
+            print(line)
+
+See https://docs.orchard.airoverflow.com for guides and the full API reference.
+"""
+from __future__ import annotations
+
+from ._bridge import LocalBridge
+from ._version import __version__
+from .client import Orchard
+from .config import Config, from_env
+from .errors import ApiError, ChannelClosedError, OrchardError, SelectorError
+
+__all__ = [
+    "Orchard",
+    "Config",
+    "from_env",
+    "OrchardError",
+    "ApiError",
+    "SelectorError",
+    "ChannelClosedError",
+    "LocalBridge",
+    "__version__",
+]

tryorchard_sdk-0.0.1/orchard_sdk/_bridge.py

@@ -0,0 +1,121 @@
+"""A local TCP listener bridged to a device WebSocket channel (adb, vnc, screen).
+
+This lets ordinary local tools reach a sandbox as if it were plugged in: the
+bridge opens a port and, for each TCP connection, opens a fresh channel to the
+device and pumps bytes both ways. So ``adb connect 127.0.0.1:<port>`` talks to
+the sandbox's adb, and a VNC viewer to its screen.
+
+It runs its own asyncio loop on a daemon thread, like :class:`SyncChannel`.
+"""
+from __future__ import annotations
+
+import asyncio
+import threading
+from typing import Any
+
+from . import _ws
+from .config import Config
+
+
+class LocalBridge:
+    """A local ``host:port`` listener forwarding to a device channel. Start it
+    (or use it as a context manager); read :attr:`port`; :meth:`close` when done.
+
+    >>> with sandbox.adb_bridge() as b:
+    ...     os.system(f"adb connect 127.0.0.1:{b.port}")
+    """
+
+    def __init__(self, cfg: Config, uuid: str, suffix: str, host: str = "127.0.0.1",
+                 port: int = 0, **params: Any):
+        self._url = _ws.ws_url(cfg, uuid, suffix, **params)
+        self.host = host
+        self._req_port = port
+        #: The bound local port (set once started; the OS picks one if port was 0).
+        self.port = 0
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+        self._server: asyncio.AbstractServer | None = None
+        self._ready = threading.Event()
+        self._err: BaseException | None = None
+
+    def start(self) -> "LocalBridge":
+        """Open the listener and return self once it is bound."""
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+        if not self._ready.wait(timeout=15):
+            raise RuntimeError("bridge did not start within 15s")
+        if self._err is not None:
+            raise self._err
+        return self
+
+    def __enter__(self) -> "LocalBridge":
+        return self.start()
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _run(self) -> None:
+        self._loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(self._loop)
+        try:
+            self._loop.run_until_complete(self._serve())
+        except BaseException as e:   # surfaced to start() via _ready/_err
+            self._err = e
+            self._ready.set()
+        finally:
+            self._loop.close()
+
+    async def _serve(self) -> None:
+        self._server = await asyncio.start_server(self._handle, self.host, self._req_port)
+        self.port = self._server.sockets[0].getsockname()[1]
+        self._ready.set()
+        async with self._server:
+            await self._server.serve_forever()
+
+    async def _handle(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        try:
+            async with _ws.connect(self._url) as ws:
+                await self._pump(ws, reader, writer)
+        except Exception:
+            with _suppress():
+                writer.close()
+
+    @staticmethod
+    async def _pump(ws: Any, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        async def to_ws() -> None:
+            try:
+                while chunk := await reader.read(65536):
+                    await ws.send(chunk)
+            except Exception:
+                pass
+            finally:
+                with _suppress():
+                    await ws.close()
+
+        async def to_local() -> None:
+            try:
+                async for msg in ws:
+                    writer.write(msg if isinstance(msg, (bytes, bytearray)) else msg.encode())
+                    await writer.drain()
+            except Exception:
+                pass
+            finally:
+                with _suppress():
+                    writer.close()
+
+        await asyncio.gather(to_ws(), to_local(), return_exceptions=True)
+
+    def close(self) -> None:
+        """Stop the listener and join the worker thread."""
+        if self._loop is not None and self._loop.is_running():
+            self._loop.call_soon_threadsafe(self._loop.stop)
+        if self._thread is not None:
+            self._thread.join(timeout=5)
+
+
+class _suppress:
+    def __enter__(self) -> None:
+        return None
+
+    def __exit__(self, *exc: object) -> bool:
+        return True   # swallow any exception in the with-body

tryorchard_sdk-0.0.1/orchard_sdk/_channels.py

@@ -0,0 +1,191 @@
+"""Synchronous wrappers over the async WebSocket core.
+
+:class:`SyncChannel` lets ordinary (non-asyncio) code consume a live channel as
+a plain iterator::
+
+    with sandbox.logs() as stream:
+        for line in stream:
+            print(line)
+
+It runs a private asyncio loop on a daemon thread, pushes decoded frames onto a
+queue, and shuts the loop down cleanly when the ``with`` block exits — including
+on ``break`` or Ctrl-C. :class:`Tunnel` drives the reverse-tunnel control channel.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+from queue import Queue
+from typing import Any, Callable, Iterator
+
+from . import _ws
+from .config import Config
+
+_SENTINEL = object()
+
+
+class SyncChannel:
+    """A live WebSocket channel exposed as a context-managed, synchronous iterator.
+
+    Args:
+        url: The fully-built channel URL (see :func:`orchard_sdk._ws.ws_url`).
+        decode: Per-frame decoder (text/json/bytes). Defaults to text.
+
+    The channel is lazy: the socket opens on ``__enter__`` and closes on
+    ``__exit__``. Iterating yields decoded frames until the stream ends or the
+    block is left. ``send()`` pushes data upstream (e.g. shell keystrokes).
+    """
+
+    def __init__(self, url: str, decode: Callable[[str | bytes], Any] = _ws.decode_text,
+                 queue_max: int = 0, open_send: str | bytes | None = None):
+        self._url = url
+        self._decode = decode
+        self._open_send = open_send
+        self._queue: "Queue[Any]" = Queue(maxsize=queue_max)
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+        self._ws: Any = None
+        self._stop = False
+        self._exc: BaseException | None = None
+
+    # -- lifecycle --------------------------------------------------------
+    def __enter__(self) -> "SyncChannel":
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _run(self) -> None:
+        self._loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(self._loop)
+        try:
+            self._loop.run_until_complete(self._pump())
+        except BaseException as e:  # surfaced to the consumer thread via the queue
+            self._exc = e
+        finally:
+            self._queue.put(_SENTINEL)
+            self._loop.close()
+
+    async def _pump(self) -> None:
+        async with _ws.connect(self._url) as ws:
+            self._ws = ws
+            if self._open_send is not None:   # e.g. a frida script sent on connect
+                await ws.send(self._open_send)
+            try:
+                async for frame in ws:
+                    if self._stop:
+                        break
+                    self._queue.put(self._decode(frame))
+            except Exception as e:  # ConnectionClosed w/ error code → re-raised to consumer
+                import websockets
+                if isinstance(e, websockets.ConnectionClosed):
+                    err = _ws._closed_err(e)
+                    if err is not None:
+                        raise err from None
+                elif not self._stop:
+                    raise
+
+    # -- consumer API -----------------------------------------------------
+    def __iter__(self) -> Iterator[Any]:
+        while True:
+            item = self._queue.get()
+            if item is _SENTINEL:
+                if self._exc is not None:
+                    raise self._exc
+                return
+            yield item
+
+    def send(self, data: str | bytes) -> None:
+        """Send a frame upstream (e.g. a shell keystroke or a resize JSON)."""
+        if self._loop is None or self._ws is None:
+            raise RuntimeError("channel not open")
+        fut = asyncio.run_coroutine_threadsafe(self._ws.send(data), self._loop)
+        fut.result(timeout=10)
+
+    def close(self) -> None:
+        """Stop the stream and join the worker thread."""
+        self._stop = True
+        if self._ws is not None and self._loop is not None and self._loop.is_running():
+            try:
+                asyncio.run_coroutine_threadsafe(self._ws.close(), self._loop).result(timeout=5)
+            except Exception:
+                pass
+        if self._thread is not None:
+            self._thread.join(timeout=5)
+
+
+class Tunnel:
+    """The reverse-tunnel control channel: forwards guest proxy connections into a
+    local proxy you run (Burp/mitmproxy). Context-managed; blocks in :meth:`run`.
+    """
+
+    def __init__(self, cfg: Config, uuid: str, to_host: str, to_port: int):
+        self._cfg = cfg
+        self._uuid = uuid
+        self._to = (to_host, to_port)
+
+    def run(self, on_event: Callable[[str, str], None] | None = None) -> int:
+        """Hold the tunnel open until the server closes it. ``on_event(level, text)``
+        receives ``ready``/``open``/``warn``/``error``/``close`` notifications."""
+        log = on_event or (lambda level, text: None)
+        return asyncio.run(self._run(log))
+
+    async def _run(self, log: Callable[[str, str], None]) -> int:
+        tasks: set[asyncio.Task] = set()
+        to_host, to_port = self._to
+
+        async def data(sid: str) -> None:
+            try:
+                async with _ws.connect(_ws.ws_url(self._cfg, self._uuid, "tunnel/data", sid=sid)) as ws:
+                    reader, writer = await asyncio.open_connection(to_host, to_port)
+                    await _pump(ws, reader, writer)
+            except Exception as e:
+                log("warn", f"stream {sid[:8]} ended: {e}")
+
+        async with _ws.connect(_ws.ws_url(self._cfg, self._uuid, "tunnel")) as control:
+            async for raw in control:
+                try:
+                    msg = json.loads(raw)
+                except Exception:
+                    continue
+                t = msg.get("t")
+                if t == "ready":
+                    log("ready", f"guest proxy -> {msg.get('proxy_target')}")
+                elif t == "open":
+                    task = asyncio.create_task(data(msg["sid"]))
+                    tasks.add(task)
+                    task.add_done_callback(tasks.discard)
+                elif t == "warn":
+                    log("warn", msg.get("detail", ""))
+                elif t == "error":
+                    log("error", msg.get("detail", "tunnel refused"))
+                    return 1
+                elif t == "close":
+                    log("close", "closed by server")
+                    return 0
+        return 0
+
+
+async def _pump(ws: Any, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+    async def to_ws() -> None:
+        try:
+            while chunk := await reader.read(65536):
+                await ws.send(chunk)
+        finally:
+            await ws.close()
+
+    async def to_local() -> None:
+        try:
+            async for msg in ws:
+                writer.write(msg if isinstance(msg, (bytes, bytearray)) else msg.encode())
+                await writer.drain()
+        finally:
+            try:
+                writer.close()
+            except Exception:
+                pass
+
+    await asyncio.gather(to_ws(), to_local(), return_exceptions=True)