steam-engine 0.1.0__py3-none-any.whl

steam_engine/__init__.py

@@ -0,0 +1,7 @@
+"""steam-engine — drive a running Steam client's internals over CDP."""
+
+from .client import SteamEngine
+from .jsproxy import JsProxy
+
+__all__ = ["SteamEngine", "JsProxy"]
+__version__ = "0.1.0"

steam_engine/cdp.py

@@ -0,0 +1,105 @@
+"""Minimal synchronous Chrome DevTools Protocol client for Steam's CEF webhelper."""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+from dataclasses import dataclass
+
+from websockets.sync.client import connect as ws_connect
+
+
+@dataclass
+class Target:
+    kind: str
+    title: str
+    url: str
+    ws_url: str
+
+
+def list_targets(port: int = 1337) -> list[Target]:
+    """GET http://127.0.0.1:<port>/json — all debuggable targets."""
+    with urllib.request.urlopen(f"http://127.0.0.1:{port}/json", timeout=5) as r:
+        raw = json.load(r)
+    return [
+        Target(
+            kind=t.get("type", ""),
+            title=t.get("title", ""),
+            url=t.get("url", ""),
+            ws_url=t.get("webSocketDebuggerUrl", ""),
+        )
+        for t in raw
+    ]
+
+
+def pick_ui_target(targets: list[Target]) -> Target | None:
+    """The SharedJSContext page — where collectionStore/appStore/SteamClient live."""
+    for t in targets:
+        if t.title == "SharedJSContext":
+            return t
+    for t in targets:
+        if "steamloopback.host" in t.url:
+            return t
+    return None
+
+
+class Session:
+    """A CDP session attached to one target. Sequential request/response only —
+    events are discarded. Not thread-safe."""
+
+    def __init__(self, ws):
+        self._ws = ws
+        self._id = 0
+
+    @classmethod
+    def connect(cls, port: int = 1337, target: Target | None = None) -> Session:
+        if target is None:
+            target = pick_ui_target(list_targets(port))
+        if target is None or not target.ws_url:
+            raise RuntimeError(
+                "SharedJSContext target not found — is Steam running with "
+                "--remote-debugging-port open?"
+            )
+        return cls(ws_connect(target.ws_url, open_timeout=10))
+
+    def eval(self, expression: str):
+        """Runtime.evaluate with returnByValue+awaitPromise. Returns result.value."""
+        self._id += 1
+        my_id = self._id
+        self._ws.send(
+            json.dumps(
+                {
+                    "id": my_id,
+                    "method": "Runtime.evaluate",
+                    "params": {
+                        "expression": expression,
+                        "returnByValue": True,
+                        "awaitPromise": True,
+                    },
+                }
+            )
+        )
+        while True:
+            msg = json.loads(self._ws.recv())
+            if msg.get("id") != my_id:
+                continue  # event or unrelated response
+            result = msg.get("result", {})
+            exc = result.get("exceptionDetails")
+            if exc:
+                desc = (
+                    exc.get("exception", {}).get("description")
+                    or exc.get("text")
+                    or "js exception"
+                )
+                raise RuntimeError(f"JS exception: {desc}")
+            return result.get("result", {}).get("value")
+
+    def eval_json(self, expression: str):
+        """Evaluate an expression that returns a JSON.stringify'ed string."""
+        v = self.eval(expression)
+        if not isinstance(v, str):
+            raise RuntimeError(f"expected JSON string result, got {type(v).__name__}")
+        return json.loads(v)
+
+    def close(self):
+        self._ws.close()

steam_engine/cli.py

@@ -0,0 +1,58 @@
+"""steam-engine CLI — generic driver commands only."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from .cdp import list_targets
+from .client import SteamEngine
+from .enable import enable as _enable
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="steam-engine",
+        description="Drive a running Steam client's internal JS (SteamClient.*, window.* stores) over CDP",
+    )
+    p.add_argument("--port", type=int,
+                   default=int(os.environ.get("STEAM_CDP_PORT", "1337")),
+                   help="remote-debugging port (env STEAM_CDP_PORT)")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("status", help="probe the CDP endpoint")
+    sub.add_parser("targets", help="list debuggable targets")
+    e = sub.add_parser("enable", help="patch webhelper wrapper (Linux)")
+    e.add_argument("--restart", action="store_true",
+                   help="kill steamwebhelper so Steam respawns it patched")
+    ev = sub.add_parser("eval", help="evaluate raw JS in SharedJSContext")
+    ev.add_argument("expr")
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+
+    if args.cmd == "enable":
+        print(_enable(args.port, restart=args.restart))
+        return 0
+    if args.cmd == "status":
+        st = SteamEngine.status(args.port)
+        print(json.dumps(st, indent=2))
+        return 0 if st["reachable"] else 1
+    if args.cmd == "targets":
+        for t in list_targets(args.port):
+            print(f"{t.kind:<10} {t.title:<35} {t.url[:80]}")
+        return 0
+    if args.cmd == "eval":
+        with SteamEngine.connect(args.port) as se:
+            print(json.dumps(se.eval(args.expr), indent=2, default=str))
+        return 0
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

steam_engine/client.py

@@ -0,0 +1,105 @@
+"""SteamEngine — main entry point.
+
+    from steam_engine import SteamEngine
+
+    with SteamEngine.connect() as se:
+        se.client.Apps.SetAppLaunchOptions(292030, "-fullscreen")
+        apps = se.window.appStore.allApps.get()
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from . import cdp
+from .enable import enable as _enable
+from .jsproxy import JsProxy
+
+
+class SteamEngine:
+    def __init__(self, session: cdp.Session):
+        self._session = session
+        self._name_cache: dict[tuple[str, str], str | None] = {}
+        # SteamClient.* — PascalCase bridge into the native client.
+        self.client = JsProxy(self, "SteamClient", convert=True)
+        # window.* — every store (collectionStore, appStore, downloadsStore, ...).
+        self.window = JsProxy(self, "window")
+
+    @classmethod
+    def connect(cls, port: int = 1337) -> SteamEngine:
+        """Attach to Steam's SharedJSContext via the remote-debugging port."""
+        return cls(cdp.Session.connect(port))
+
+    def __enter__(self) -> SteamEngine:
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    def close(self):
+        self._session.close()
+
+    # ---- low level ------------------------------------------------------
+
+    def eval(self, expression: str) -> Any:
+        """Evaluate raw JS in SharedJSContext. Returns result.value."""
+        return self._session.eval(expression)
+
+    def eval_json(self, expression: str) -> Any:
+        return self._session.eval_json(expression)
+
+    def get(self, path: str) -> Any:
+        return self._session.eval_json(f"JSON.stringify({path})")
+
+    def _resolve_name(self, parent: str, name: str) -> str | None:
+        """Find the real member name on `parent`, ignoring case/underscores —
+        so `get_os_type` finds `GetOSType`."""
+        key = name.replace("_", "").lower()
+        cache_key = (parent, key)
+        if cache_key not in self._name_cache:
+            self._name_cache[cache_key] = self._session.eval_json(
+                f"JSON.stringify(Object.getOwnPropertyNames({parent})"
+                f".find(n=>n.toLowerCase()==={json.dumps(key)}) ?? null)"
+            )
+        return self._name_cache[cache_key]
+
+    def call(self, path: str, *args: Any, convert: bool = False) -> Any:
+        """Call `path(...args)`; args are JSON-serialized. Awaits promises.
+        Returns the JSON-decoded result, or None for undefined/unserializable."""
+        if convert:
+            parent, _, leaf = path.rpartition(".")
+            resolved = self._resolve_name(parent, leaf)
+            if resolved:
+                path = f"{parent}.{resolved}"
+        arglist = ",".join(json.dumps(a) for a in args)
+        expr = (
+            "(async()=>{"
+            f"const r = await {path}({arglist});"
+            "try { return JSON.stringify({v: r === undefined ? null : r}); }"
+            "catch { return JSON.stringify({v: null, unserializable: typeof r}); }"
+            "})()"
+        )
+        out = self._session.eval(expr)
+        return json.loads(out).get("v") if isinstance(out, str) else out
+
+    # ---- enable / status ------------------------------------------------
+
+    @staticmethod
+    def status(port: int = 1337) -> dict:
+        """Probe the debug endpoint without attaching a session."""
+        try:
+            targets = cdp.list_targets(port)
+        except Exception as e:
+            return {"reachable": False, "error": str(e), "port": port}
+        return {
+            "reachable": True,
+            "port": port,
+            "targets": len(targets),
+            "shared_js_context": any(t.title == "SharedJSContext" for t in targets),
+        }
+
+    @staticmethod
+    def enable(port: int = 1337, restart: bool = False) -> str:
+        """Patch the webhelper wrapper so it opens the debug port (Linux)."""
+        return _enable(port, restart)

steam_engine/enable.py

@@ -0,0 +1,64 @@
+"""Enable the CEF remote-debugging port on the Steam client."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+WRAP = "ubuntu12_64/steamwebhelper_sniper_wrap.sh"
+EXEC_LINE = 'exec ./steamwebhelper "$@"'
+
+
+def _steam_dir() -> Path | None:
+    home = Path.home()
+    candidates = [
+        home / ".local/share/Steam",
+        home / ".steam/steam",
+        home / ".var/app/com.valvesoftware.Steam/.local/share/Steam",  # flatpak
+    ]
+    for c in candidates:
+        if (c / WRAP).exists():
+            return c
+    return None
+
+
+def enable(port: int = 1337, restart: bool = False) -> str:
+    """Patch steamwebhelper_sniper_wrap.sh to pass --remote-debugging-port.
+    Returns a human-readable status message."""
+    if sys.platform != "linux":
+        raise RuntimeError(
+            "on this platform, launch Steam with -cef-enable-debugging "
+            "(Windows/macOS) or inject --remote-debugging-port into the "
+            "steamwebhelper command line"
+        )
+    steam = _steam_dir()
+    if steam is None:
+        raise RuntimeError("could not locate " + WRAP)
+    wrap = steam / WRAP
+    body = wrap.read_text()
+    if "--remote-debugging-port" in body:
+        msg = f"{wrap} already patched"
+    else:
+        if EXEC_LINE not in body:
+            raise RuntimeError(
+                f"unexpected wrap script contents - edit {wrap} manually"
+            )
+        patched = (
+            "exec ./steamwebhelper --remote-debugging-address=127.0.0.1 "
+            f"--remote-debugging-port={port} \"$@\""
+        )
+        wrap.with_suffix(".sh.bak").write_text(body)
+        wrap.write_text(body.replace(EXEC_LINE, patched))
+        msg = f"patched {wrap}"
+    if restart:
+        # the browser process is the only one carrying -uimode in argv
+        r = subprocess.run(["pkill", "-f", "steamwebhelper.*-uimode"])
+        msg += (
+            "; steamwebhelper killed - Steam will respawn it with the debug port"
+            if r.returncode == 0
+            else "; no running steamwebhelper found"
+        )
+    else:
+        msg += "; restart Steam (or pass restart=True) to activate"
+    return msg

steam_engine/jsproxy.py

@@ -0,0 +1,64 @@
+"""Lazy JS path proxy — `se.client.Apps.RunGame(123)` evaluates
+`SteamClient.Apps.RunGame(123)` in the page; `se.window.appStore.allApps.get()`
+reads the property. Nothing is bound until called, so the entire
+SteamClient.* / window.* surface is reachable without hand-written bindings."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Protocol
+
+
+class Engine(Protocol):
+    """What a proxy needs from its host — any object providing these works,
+    including test doubles."""
+
+    def call(self, path: str, *args: Any, convert: bool = False) -> Any: ...
+    def get(self, path: str) -> Any: ...
+    def eval_json(self, expression: str) -> Any: ...
+
+
+def _to_js_name(name: str, convert: bool) -> str:
+    """snake_case/lowerCamel -> PascalCase, for SteamClient.* ergonomics."""
+    if not convert:
+        return name
+    if "_" in name:
+        return "".join(p.title() for p in name.split("_") if p)
+    if name[:1].islower():
+        return name[0].upper() + name[1:]
+    return name
+
+
+class JsProxy:
+    __slots__ = ("_se", "_path", "_convert")
+
+    def __init__(self, se: Engine, path: str, convert: bool = False):
+        self._se = se
+        self._path = path
+        self._convert = convert
+
+    def __getattr__(self, name: str) -> JsProxy:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return JsProxy(
+            self._se, f"{self._path}.{_to_js_name(name, self._convert)}", self._convert
+        )
+
+    def __getitem__(self, key) -> JsProxy:
+        return JsProxy(self._se, f"{self._path}[{json.dumps(key)}]", self._convert)
+
+    def __call__(self, *args: Any) -> Any:
+        return self._se.call(self._path, *args, convert=self._convert)
+
+    def get(self) -> Any:
+        """Read the property value (must be JSON-serializable)."""
+        return self._se.get(self._path)
+
+    def keys(self) -> list[str]:
+        """Own property names — handy when .get() hits unserializable objects."""
+        return self._se.eval_json(
+            f"JSON.stringify(Object.getOwnPropertyNames({self._path}))"
+        )
+
+    def __repr__(self) -> str:
+        return f"<JsProxy {self._path}>"

steam_engine-0.1.0.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.5
+Name: steam-engine
+Version: 0.1.0
+Summary: Drive a running Steam client's internals over Chrome DevTools Protocol (collections, apps, downloads, all of SteamClient.*)
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: websockets>=12
+Description-Content-Type: text/markdown
+
+# steam-engine
+
+Call a running Steam client’s internal JavaScript API from Python.
+
+`steam-engine` connects to Steam’s CEF renderer over Chrome DevTools Protocol. It exposes `SteamClient.*` methods and `window.*` stores through a Python proxy, so operations run through Steam itself.
+
+For a higher-level collections API, see the sibling project `steam-collections`.
+
+## Get started
+
+Install from the repository, then enable debugging in Steam:
+
+```sh
+pip install -e .
+steam-engine enable --restart
+steam-engine status
+```
+
+`enable` is Linux-only. It patches `ubuntu12_64/steamwebhelper_sniper_wrap.sh` and backs up the original to `.sh.bak`. Steam updates can replace this wrapper; run `enable` again if the connection stops working.
+
+On Windows or macOS, launch Steam with `-cef-enable-debugging` or add `--remote-debugging-port` to the webhelper command line.
+
+The default port is `1337`. Set `STEAM_CDP_PORT` to use another port.
+
+## Use from Python
+
+Steam must be running with debugging enabled.
+
+```python
+from steam_engine import SteamEngine
+
+with SteamEngine.connect() as se:
+    # Call Steam's native bridge.
+    se.client.Apps.SetAppLaunchOptions(292030, "-fullscreen")
+
+    # Snake_case works too.
+    se.client.Apps.specify_compat_tool(105600, "proton_experimental")
+
+    # Read a JavaScript property.
+    apps = se.window.appStore.allApps.get()
+
+    # Run JavaScript directly.
+    count = se.eval("collectionStore.userCollections.length")
+```
+
+The proxy supports:
+
+| Syntax                | Behavior                                                     |
+| --------------------- | ------------------------------------------------------------ |
+| `proxy.method(*args)` | Call a method with JSON-serialized arguments; await promises |
+| `proxy.prop.get()`    | Read a JSON-serializable property                            |
+| `proxy.prop.keys()`   | List own property names                                      |
+| `proxy.prop[index]`   | Access an indexed value                                      |
+
+Method names ignore case and underscores. Results are JSON-decoded; `undefined` and unserializable results become `None`.
+
+## Use from the terminal
+
+```sh
+steam-engine status             # Check the connection
+steam-engine targets            # List debuggable targets
+steam-engine enable --restart   # Enable debugging and restart Steam (Linux)
+steam-engine eval 'collectionStore.userCollections.length'
+```
+
+## API reference
+
+The generated reference in `docs/` lists the discovered methods and stores. To refresh and browse it:
+
+```sh
+python scripts/dump_api_surface.py
+mkdocs serve
+```
+
+Raw data is available at `docs/data/api_surface.json`.
+
+Steam’s internal API is undocumented. Method names and arguments can change between client builds.
+

steam_engine-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+steam_engine/__init__.py,sha256=fw8dMIs-pakiaY7A4l0LtQLvN81ESOsLyq8aH0TR9js,196
+steam_engine/cdp.py,sha256=qdROL3SwuEOpuzY_1A-EJFPA6ZVEDE5VkSnapINUz9o,3298
+steam_engine/cli.py,sha256=q1FAhWHltWg1iIvLFpVP7iIzYxy0oIHPQfMSZpW6--k,1871
+steam_engine/client.py,sha256=N7kksLvOeZC-rDdQoKvR_ru0nUh_IqOF0rol5nZ2HT4,3873
+steam_engine/enable.py,sha256=BLIcE4gNanVs5zhmn1dN23cMl_0ZXafxoc3j6PoPVkc,2165
+steam_engine/jsproxy.py,sha256=D7iE1qiIAbYpHHonnACCAVMZ2b46D3vomctrjQHWEW4,2160
+steam_engine-0.1.0.dist-info/METADATA,sha256=MG_oSMQlBVxZ2Ijy8ULfEsHTpkTsuc8gAcIfG2wX_xE,3060
+steam_engine-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+steam_engine-0.1.0.dist-info/entry_points.txt,sha256=RdL_xC83JMOIk2pePftOlnQswaKGyfiQNh4CcWDFuJU,55
+steam_engine-0.1.0.dist-info/RECORD,,

steam_engine-0.1.0.dist-info/WHEEL

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

steam_engine-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+steam-engine = steam_engine.cli:main