skool-api-mcp 1.0.2__py3-none-any.whl

skool_api_mcp/__init__.py

@@ -0,0 +1,28 @@
+"""Self-hosted API and MCP server for one app (see app.py). Personal use only, see LICENSE.
+
+From Python, without a server:
+
+    from skool_api_mcp import call
+    groups = call("list_groups")["groups"]
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+__version__ = "1.0.2"
+
+
+def call(tool: str, args: dict[str, Any] | None = None, **kwargs: Any) -> Any:
+    """Run one tool with the saved session and return its answer. Raises ToolError on failure."""
+    from skool_api_mcp.runner import Runner
+
+    async def go() -> Any:
+        runner = Runner()
+        try:
+            return await runner.run(tool, {**(args or {}), **kwargs})
+        finally:
+            await runner.close()
+
+    return asyncio.run(go())

skool_api_mcp/api.py

@@ -0,0 +1,213 @@
+"""The REST API and the MCP endpoint on one port.
+
+- `GET|POST|PUT|PATCH|DELETE <app.API_PREFIX>/<route>`: each tool at its route, the same paths as the
+  hosted API at cotlet.dev. Path parts and the query string are arguments; a JSON body adds the rest.
+- `POST <app.API_PREFIX>/tools/{name}`: any tool by name, the JSON body is its arguments.
+- `GET <app.API_PREFIX>/tools`: every tool with its schema. OpenAPI at `/docs` and `/openapi.json`.
+- `/mcp`: the MCP server over streamable HTTP.
+
+With <ENV>_MCP_TOKEN set, every request needs `Authorization: Bearer <token>`.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hmac
+import json
+import os
+import re
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
+
+from skool_api_mcp import __version__, app, mcp_server
+from skool_api_mcp.core.errors import HTTP_STATUS, ErrorCode, ToolError
+from skool_api_mcp.core.tools import ToolSpec
+from skool_api_mcp.runner import Runner, description, tools
+
+PREFIX = app.API_PREFIX
+ASGI = Callable[[dict[str, Any], Callable[[], Awaitable[Any]], Callable[[Any], Awaitable[None]]], Awaitable[None]]
+
+
+def _error(code: ErrorCode, message: str) -> JSONResponse:
+    return JSONResponse({"error": code.value, "message": message}, status_code=HTTP_STATUS.get(code, 500))
+
+
+def _typed(value: str, schema: dict[str, Any]) -> Any:
+    kind = schema.get("type")
+    try:
+        if kind == "integer":
+            return int(value)
+        if kind == "number":
+            return float(value)
+    except ValueError:
+        return value
+    if kind == "boolean":
+        return value.lower() in ("1", "true", "yes", "on")
+    if kind == "array":
+        return [_typed(v, schema.get("items") or {}) for v in value.split(",") if v]
+    if kind == "object":
+        with contextlib.suppress(ValueError):
+            return json.loads(value)
+    return value
+
+
+def _route_order(spec: ToolSpec) -> list[int]:
+    """Literal segments before {placeholders}, so /groups/discover wins over /groups/{group}."""
+    path = (spec.route or "").split(" ", 1)[1]
+    return [1 if part.startswith("{") else 0 for part in path.strip("/").split("/")]
+
+
+def _tag(path: str) -> str:
+    """OpenAPI group: the part after /groups/{group}/ (posts, members ...), else the first part."""
+    parts = path.strip("/").split("/")
+    return parts[2] if parts[:2] == ["groups", "{group}"] and len(parts) > 2 else parts[0]
+
+
+def _openapi(spec: ToolSpec, method: str, path: str) -> dict[str, Any]:
+    props: dict[str, Any] = spec.input_schema.get("properties") or {}
+    required = set(spec.input_schema.get("required") or [])
+    in_path = set(re.findall(r"\{(\w+)\}", path))
+    parameters = [
+        {"name": name, "in": "path", "required": True, "schema": props.get(name, {"type": "string"})}
+        for name in in_path
+    ]
+    rest = {k: v for k, v in props.items() if k not in in_path}
+    extra: dict[str, Any] = {}
+    if method == "GET":
+        parameters += [
+            {"name": name, "in": "query", "required": name in required, "schema": schema}
+            for name, schema in rest.items()
+        ]
+    elif rest:
+        body = {"type": "object", "properties": rest, "required": sorted(required - in_path)}
+        extra["requestBody"] = {"required": bool(body["required"]), "content": {"application/json": {"schema": body}}}
+    if spec.example_response:
+        extra["responses"] = {
+            "200": {"description": "OK", "content": {"application/json": {"example": spec.example_response}}}
+        }
+    return {"parameters": parameters, **extra}
+
+
+async def _arguments(request: Request, spec: ToolSpec) -> dict[str, Any]:
+    props: dict[str, Any] = spec.input_schema.get("properties") or {}
+    args: dict[str, Any] = {}
+    if request.method != "GET":
+        raw = await request.body()
+        if raw.strip():
+            try:
+                body = json.loads(raw)
+            except ValueError:
+                raise ToolError("The body must be a JSON object.", ErrorCode.INVALID_INPUT) from None
+            if not isinstance(body, dict):
+                raise ToolError("The body must be a JSON object.", ErrorCode.INVALID_INPUT)
+            args.update(body)
+    for name in request.query_params:
+        values = request.query_params.getlist(name)
+        schema = props.get(name) or {}
+        args[name] = (
+            [_typed(v, schema.get("items") or {}) for v in values]
+            if schema.get("type") == "array" and len(values) > 1
+            else _typed(values[-1], schema)
+        )
+    for name, value in request.path_params.items():
+        args[name] = _typed(value, props.get(name) or {})
+    return args
+
+
+def create_app(runner: Runner) -> ASGI:
+    manager = StreamableHTTPSessionManager(app=mcp_server.build(runner), json_response=True, stateless=True)
+    token = os.environ.get(f"{app.ENV}_MCP_TOKEN", "").strip()
+
+    @contextlib.asynccontextmanager
+    async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+        async with manager.run():
+            yield
+        await runner.close()
+
+    api = FastAPI(
+        title=f"{app.NAME} API (self-hosted)",
+        version=__version__,
+        description=f"Your {app.NAME} account as a REST API, run on your machine with your Chrome's session.",
+        lifespan=lifespan,
+    )
+
+    async def call(spec: ToolSpec, args: dict[str, Any]) -> JSONResponse:
+        try:
+            result = await runner.run(spec.name, args)
+        except ToolError as exc:
+            return _error(exc.code, str(exc))
+        return JSONResponse(result)
+
+    def endpoint(spec: ToolSpec) -> Callable[[Request], Awaitable[JSONResponse]]:
+        async def handle(request: Request) -> JSONResponse:
+            try:
+                args = await _arguments(request, spec)
+            except ToolError as exc:
+                return _error(exc.code, str(exc))
+            return await call(spec, args)
+
+        return handle
+
+    @api.get(f"{PREFIX}/tools", summary="Every tool with its route and input schema")
+    async def list_tools() -> list[dict[str, Any]]:
+        return [
+            {
+                "name": spec.name,
+                "title": spec.title,
+                "access": spec.access,
+                "route": spec.route,
+                "description": description(spec),
+                "input_schema": spec.input_schema,
+                "example_response": spec.example_response,
+            }
+            for spec in tools(runner.read_only)
+        ]
+
+    @api.post(f"{PREFIX}/tools/{{name}}", summary="Call any tool by name; the JSON body is its arguments")
+    async def call_by_name(name: str, request: Request) -> JSONResponse:
+        raw = await request.body()
+        try:
+            args = json.loads(raw) if raw.strip() else {}
+        except ValueError:
+            return _error(ErrorCode.INVALID_INPUT, "The body must be a JSON object.")
+        if not isinstance(args, dict):
+            return _error(ErrorCode.INVALID_INPUT, "The body must be a JSON object.")
+        spec = next((s for s in tools() if s.name == name), None)
+        if spec is None:
+            return _error(ErrorCode.UNKNOWN_TOOL, f"No tool '{name}'. GET {PREFIX}/tools lists them.")
+        return await call(spec, args)
+
+    for spec in sorted(tools(runner.read_only), key=_route_order):
+        method, path = (spec.route or "").split(" ", 1)
+        api.add_api_route(
+            PREFIX + path,
+            endpoint(spec),
+            methods=[method],
+            name=spec.name,
+            operation_id=spec.name,
+            summary=spec.title,
+            description=description(spec),
+            tags=[_tag(path)],
+            openapi_extra=_openapi(spec, method, path),
+        )
+
+    async def asgi(
+        scope: dict[str, Any], receive: Callable[[], Awaitable[Any]], send: Callable[[Any], Awaitable[None]]
+    ) -> None:
+        if scope["type"] == "http" and token:
+            sent = dict(scope.get("headers") or []).get(b"authorization", b"").decode()
+            if not hmac.compare_digest(sent, f"Bearer {token}"):
+                await _error(ErrorCode.AUTH_REQUIRED, f"Send Authorization: Bearer <{app.ENV}_MCP_TOKEN>.")(
+                    scope, receive, send
+                )
+                return
+        if scope["type"] == "http" and (scope["path"] == "/mcp" or scope["path"].startswith("/mcp/")):
+            await manager.handle_request(scope, receive, send)
+            return
+        await api(scope, receive, send)
+
+    return asgi

skool_api_mcp/app.py

@@ -0,0 +1,29 @@
+"""Everything the server knows about Skool outside `skool/`: names, domains and the session cookie.
+
+The rest of the package reads these values and never names the app itself.
+"""
+
+from __future__ import annotations
+
+NAME = "Skool"
+SLUG = "skool"
+# The command and the prefix of every environment variable (SKOOL_AUTH_TOKEN, SKOOL_MCP_TOKEN ...).
+CLI = "skool-mcp"
+ENV = "SKOOL"
+# Requests may reach only these hosts and their subdomains. Their cookies are read from Chrome.
+DOMAINS = ("skool.com",)
+# Present only while signed in. The first is the cookie a pasted token sets.
+SESSION_COOKIES = ("auth_token",)
+COOKIE_DOMAIN = ".skool.com"
+LOGIN_URL = "https://www.skool.com/login"
+# A final URL with one of these means the app signed the session out.
+LOGGED_OUT_MARKERS = ("/login",)
+# An answer with one of these asks you to sign in again before a sensitive action. Skool has none.
+RELOGIN_MARKERS: tuple[str, ...] = ()
+# Paths of your Skool account that tools may read but never write. Common password, email and sign-in
+# paths are refused for every app (core/account_guard.py); Skool adds none.
+ACCOUNT_PATHS: tuple[str, ...] = ()
+# REST routes live under this path, the same as on cotlet.dev.
+API_PREFIX = "/api/v1/skool"
+# Prepended to the MCP server's instructions: where an agent starts.
+AGENT_START = "Start with list_groups: its `group` values are what every other tool takes."

skool_api_mcp/cli.py

@@ -0,0 +1,198 @@
+"""<cli>: connect your Chrome, then run the REST API and MCP server, or call one tool.
+
+<cli> connect          # read your session of the app from Chrome (remote debugging on)
+<cli> status           # which account the saved session is
+<cli> tools            # every tool, read or write
+<cli> call <tool> k=v  # one tool, arguments as JSON or key=value
+<cli> mcp              # MCP server over stdio, for Claude Code, Claude Desktop, Cursor
+<cli> serve            # REST API + MCP over HTTP on http://127.0.0.1:8787
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import getpass
+import ipaddress
+import json
+import os
+import sys
+from typing import Any
+from urllib.parse import urlsplit
+
+from skool_api_mcp import __version__, app
+from skool_api_mcp import session as sessions
+from skool_api_mcp.core.errors import ToolError
+from skool_api_mcp.runner import Runner, all_tools, tools
+
+
+def _connect(args: argparse.Namespace) -> None:
+    if args.token:
+        token = getpass.getpass("auth_token cookie value (input hidden): ")
+        session = sessions.from_token(token)
+    else:
+        if not args.cdp:
+            print("Connecting to Chrome. Click Allow if Chrome asks about remote debugging.", file=sys.stderr)
+        session = sessions.from_chrome(args.cdp, args.profile_dir)
+    path = sessions.save(session)
+    who = asyncio.run(_whoami())
+    print(f"Saved {len(session.cookies)} {app.NAME} cookies to {path}")
+    print(f"Signed in to {app.NAME} as {who}" if who else f"Saved, but {app.NAME} did not confirm the session.")
+
+
+async def _whoami() -> str | None:
+    from skool_api_mcp.core.context import ToolContext
+    from skool_api_mcp.skool.auth import whoami
+
+    ctx = ToolContext(session=sessions.load())
+    try:
+        return await whoami(ctx)
+    except ToolError:
+        return None
+    finally:
+        await ctx.close()
+
+
+def _status(_: argparse.Namespace) -> None:
+    session = sessions.load()
+    if not session.signed_in:
+        sys.exit(f"No {app.NAME} session. Run: {app.CLI} connect")
+    who = asyncio.run(_whoami())
+    if not who:
+        sys.exit(f"{app.NAME} signed this session out. Sign in to {app.NAME} in Chrome, then run: {app.CLI} connect")
+    source = {"auto": "your Chrome", "token": "a pasted token", None: f"{app.ENV}_AUTH_TOKEN"}.get(
+        session.source, f"Chrome at {urlsplit(session.source or '').netloc}"
+    )
+    print(f"Signed in to {app.NAME} as {who} (session from {source}, {sessions.session_path()})")
+
+
+def _tools(args: argparse.Namespace) -> None:
+    specs = tools(args.read_only)
+    if args.json:
+        rows = [{"name": s.name, "access": s.access, "route": s.route, "input_schema": s.input_schema} for s in specs]
+        print(json.dumps(rows, indent=2))
+        return
+    for spec in specs:
+        print(f"{spec.name:<30} {spec.access:<5} {spec.route:<62} {spec.description}")
+
+
+def _parse_args(tool: str, pairs: list[str]) -> dict[str, Any]:
+    """key=value pairs; a value is JSON unless the tool's schema wants a string (IDs like 148213977)."""
+    if len(pairs) == 1 and pairs[0].lstrip().startswith("{"):
+        return json.loads(pairs[0])
+    spec = all_tools().get(tool)
+    properties = spec.input_schema.get("properties", {}) if spec else {}
+    out: dict[str, Any] = {}
+    for pair in pairs:
+        key, sep, value = pair.partition("=")
+        if not sep:
+            sys.exit(f"Arguments are key=value or one JSON object, got {pair!r}")
+        if properties.get(key, {}).get("type") == "string":
+            out[key] = value
+            continue
+        try:
+            out[key] = json.loads(value)
+        except ValueError:
+            out[key] = value
+    return out
+
+
+def _call(args: argparse.Namespace) -> None:
+    runner = Runner(read_only=args.read_only)
+
+    async def go() -> Any:
+        try:
+            return await runner.run(args.tool, _parse_args(args.tool, args.arguments))
+        finally:
+            await runner.close()
+
+    try:
+        result = asyncio.run(go())
+    except ToolError as exc:
+        sys.exit(f"{exc.code}: {exc}")
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+
+def _mcp(args: argparse.Namespace) -> None:
+    from skool_api_mcp.mcp_server import run_stdio
+
+    asyncio.run(run_stdio(Runner(read_only=args.read_only)))
+
+
+def _serve(args: argparse.Namespace) -> None:
+    import uvicorn
+
+    from skool_api_mcp.api import create_app
+
+    try:
+        loopback = ipaddress.ip_address(args.host).is_loopback
+    except ValueError:
+        loopback = args.host == "localhost"
+    if not loopback and not os.environ.get(f"{app.ENV}_MCP_TOKEN"):
+        sys.exit(
+            f"Listening beyond this machine needs {app.ENV}_MCP_TOKEN, or anyone on the network can use your {app.NAME} account."
+        )
+    print(
+        f"REST API  http://{args.host}:{args.port}{app.API_PREFIX}   docs http://{args.host}:{args.port}/docs",
+        file=sys.stderr,
+    )
+    print(f"MCP       http://{args.host}:{args.port}/mcp", file=sys.stderr)
+    uvicorn.run(create_app(Runner(read_only=args.read_only)), host=args.host, port=args.port, log_level="warning")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog=app.CLI,
+        description=(__doc__ or "").replace("<cli>", app.CLI),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("connect", help=f"read your {app.NAME} session from Chrome and save it")
+    p.add_argument(
+        "--cdp", help="DevTools address of a Chrome started with --remote-debugging-port, e.g. http://127.0.0.1:9222"
+    )
+    p.add_argument("--profile-dir", help="Chrome profile folder holding DevToolsActivePort, when not the default")
+    p.add_argument("--token", action="store_true", help="paste the auth_token cookie by hand instead")
+    p.set_defaults(func=_connect)
+
+    p = sub.add_parser("status", help=f"check the saved session with {app.NAME}")
+    p.set_defaults(func=_status)
+
+    for name, func, text in (
+        ("tools", _tools, "list the tools"),
+        ("mcp", _mcp, "MCP server over stdio"),
+        ("serve", _serve, "REST API and MCP over HTTP"),
+    ):
+        p = sub.add_parser(name, help=text)
+        p.add_argument(
+            "--read-only",
+            action="store_true",
+            default=os.environ.get(f"{app.ENV}_MCP_READ_ONLY") == "1",
+            help="only tools that read",
+        )
+        p.set_defaults(func=func)
+        if name == "tools":
+            p.add_argument("--json", action="store_true", help="names, routes and input schemas as JSON")
+        if name == "serve":
+            p.add_argument("--host", default=os.environ.get(f"{app.ENV}_MCP_HOST", "127.0.0.1"))
+            p.add_argument("--port", type=int, default=int(os.environ.get(f"{app.ENV}_MCP_PORT", "8787")))
+
+    p = sub.add_parser("call", help="run one tool and print its JSON answer")
+    p.add_argument("tool")
+    p.add_argument("arguments", nargs="*", help="key=value pairs or one JSON object, e.g. group=yourgroup limit=10")
+    p.add_argument("--read-only", action="store_true")
+    p.set_defaults(func=_call)
+
+    args = parser.parse_args()
+    try:
+        args.func(args)
+    except ToolError as exc:
+        sys.exit(f"{exc.code}: {exc}")
+    except KeyboardInterrupt:
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()

skool_api_mcp/core/account_guard.py

@@ -0,0 +1,33 @@
+"""Tools never change your account in the app: password, email, sign-in, two-factor, profile.
+
+Checked on every request a tool makes, before it leaves. Reads stay allowed ("who am I" is a profile GET);
+any other method to an account path is refused. The common paths are matched for every app, the app adds
+its own in `app.ACCOUNT_PATHS`.
+"""
+
+from __future__ import annotations
+
+import re
+from urllib.parse import urlsplit
+
+from skool_api_mcp import app
+from skool_api_mcp.core.errors import ErrorCode, ToolError
+
+_READS = frozenset({"GET", "HEAD", "OPTIONS"})
+_COMMON = re.compile(
+    r"passw|two[-_]?factor|2fa|(^|[/_-])(mfa|totp|otp)([/_-]|$)|recovery[-_]?code|"
+    r"(change|update|verify)[-_]?email|email[-_]?(change|update)|"
+    r"(delete|deactivate|close)[-_]?account|account[-_/](delete|deactivate|close)|"
+    r"(^|/)(log[-_]?out|sign[-_]?out|log[-_]?in|sign[-_]?in)([/?]|$)"
+)
+
+
+def check_account_write(method: str, url: str) -> None:
+    if method.upper() in _READS:
+        return
+    path = urlsplit(url).path.lower()
+    if _COMMON.search(path) or any(re.search(pattern, path, re.IGNORECASE) for pattern in app.ACCOUNT_PATHS):
+        raise ToolError(
+            "This server never changes account settings in the app (password, email, sign-in, profile).",
+            ErrorCode.SCOPE_DENIED,
+        )

skool_api_mcp/core/context.py

@@ -0,0 +1,175 @@
+"""What a tool function gets besides its input: a ready HTTP client with your session of the app.
+
+Requests go out with curl_cffi, which copies Chrome's TLS and HTTP/2 fingerprint, so the app sees the same
+kind of client as your browser. Only the app's hosts (`app.DOMAINS`) are reachable, redirects included.
+"""
+
+from __future__ import annotations
+
+import json as jsonlib
+import time
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import urljoin, urlsplit
+
+from curl_cffi.requests import AsyncSession, BrowserType
+
+from skool_api_mcp import app
+from skool_api_mcp.core.account_guard import check_account_write
+from skool_api_mcp.core.errors import AuthExpiredError, CaptchaRequiredError, ErrorCode, ToolError
+from skool_api_mcp.session import Session
+
+DOMAINS = app.DOMAINS
+_REDIRECTS = {301, 302, 303, 307, 308}
+_MAX_REDIRECTS = 10
+_TARGETS = {member.value for member in BrowserType}
+_CHALLENGE_MARKERS = ("cf-chl", "challenge-platform", "Just a moment...", "cf_chl_opt")
+_CAPTCHA_MARKERS = ("g-recaptcha", "h-captcha", "cf-turnstile")
+_LOGGED_OUT_MARKERS = app.LOGGED_OUT_MARKERS
+
+
+@dataclass(frozen=True)
+class HttpResponse:
+    status: int
+    url: str
+    headers: dict[str, str]
+    text: str
+
+    def json(self) -> Any:
+        try:
+            return jsonlib.loads(self.text)
+        except ValueError as exc:
+            raise ToolError(f"{app.NAME} answered with something that is not JSON.", ErrorCode.TARGET_ERROR) from exc
+
+
+def allowed_host(url: str) -> bool:
+    host = (urlsplit(url).hostname or "").lower()
+    return any(host == domain or host.endswith(f".{domain}") for domain in DOMAINS)
+
+
+def impersonate_target(chrome_major: int | None) -> str:
+    """The exact Chrome version when curl_cffi has it, otherwise its newest Chrome profile."""
+    target = f"chrome{chrome_major}"
+    return target if chrome_major and target in _TARGETS else "chrome"
+
+
+def _raise_for(response: HttpResponse) -> None:
+    final_url = response.url.lower()
+    if response.status == 401 or any(marker in final_url for marker in _LOGGED_OUT_MARKERS):
+        raise AuthExpiredError(
+            f"{app.NAME} signed this session out. Sign in to {app.NAME} in Chrome, then run: {app.CLI} connect"
+        )
+    if response.status == 429:
+        raise ToolError(f"{app.NAME} is rate limiting this account. Try again later.", ErrorCode.RATE_LIMITED)
+    head = response.text[:20000]
+    if response.status in (401, 403) and any(marker in head for marker in app.RELOGIN_MARKERS):
+        raise AuthExpiredError(
+            f"{app.NAME} asks you to sign in again before this action. Sign out and in again at "
+            f"{app.LOGIN_URL} in Chrome, then run: {app.CLI} connect"
+        )
+    if response.status in (200, 403) and any(marker in head for marker in _CAPTCHA_MARKERS):
+        raise CaptchaRequiredError(
+            f"{app.NAME} asks for a CAPTCHA. Open {app.DOMAINS[0]} in Chrome, finish it, then try again."
+        )
+    if response.status in (403, 503) and (
+        response.headers.get("cf-mitigated") == "challenge" or any(marker in head for marker in _CHALLENGE_MARKERS)
+    ):
+        raise ToolError(
+            f"{app.NAME} showed a bot check. Open {app.DOMAINS[0]} in Chrome once, then try again.",
+            ErrorCode.TARGET_BLOCKED,
+        )
+    if response.status == 403:
+        raise ToolError(f"{app.NAME} refused the request (403).", ErrorCode.TARGET_BLOCKED)
+
+
+@dataclass
+class ToolContext:
+    session: Session
+    timeout_s: float = 30.0
+    _cache: dict[str, tuple[float, str]] = field(default_factory=dict, repr=False)
+    _http: AsyncSession | None = field(default=None, repr=False)
+
+    def _client(self) -> AsyncSession:
+        if self._http is None:
+            headers = {"accept-language": self.session.locale or "en-US,en;q=0.9"}
+            target = impersonate_target(self.session.chrome_major)
+            # The browser's own user agent only when the TLS fingerprint matches its version.
+            if self.session.user_agent and target != "chrome":
+                headers["user-agent"] = self.session.user_agent
+            self._http = AsyncSession(impersonate=target, proxy=self.session.proxy or None, headers=headers)  # pyright: ignore[reportArgumentType] - target is a BrowserType value
+            for cookie in self.session.cookies:
+                self._http.cookies.set(
+                    cookie["name"], cookie["value"], domain=cookie["domain"], path=cookie.get("path", "/")
+                )
+        return self._http
+
+    async def call(self, method: str, url: str, **kwargs: Any) -> HttpResponse:
+        """One request to the app with your cookies. A signed-out answer raises auth_expired.
+
+        Writes to your account settings in the app are refused before they leave (account_guard).
+        """
+        if not allowed_host(url):
+            raise ToolError(f"Request outside {app.DOMAINS[0]}.", ErrorCode.INTERNAL_ERROR)
+        check_account_write(method, url)
+        client = self._client()
+        method = method.upper()
+        params, json, data, headers = (
+            kwargs.get("params"),
+            kwargs.get("json"),
+            kwargs.get("data"),
+            kwargs.get("headers"),
+        )
+        for _ in range(_MAX_REDIRECTS + 1):
+            try:
+                raw = await client.request(
+                    method,  # pyright: ignore[reportArgumentType] - an HTTP method name
+                    url,
+                    params=params,
+                    json=json,
+                    data=data,
+                    headers=headers,
+                    timeout=self.timeout_s,
+                    allow_redirects=False,
+                )
+            except Exception as exc:
+                raise ToolError(f"{app.NAME} did not answer: {type(exc).__name__}.", ErrorCode.TARGET_ERROR) from exc
+            location = raw.headers.get("location")
+            if raw.status_code not in _REDIRECTS or not location:
+                break
+            url = urljoin(str(raw.url), location)
+            if not allowed_host(url):
+                raise ToolError(f"{app.NAME} redirected outside {app.DOMAINS[0]}.", ErrorCode.TARGET_ERROR)
+            params = None
+            if raw.status_code == 303 or (raw.status_code in (301, 302) and method == "POST"):
+                method, json, data = "GET", None, None
+        else:
+            raise ToolError("Too many redirects.", ErrorCode.TARGET_ERROR)
+        response = HttpResponse(
+            status=raw.status_code,
+            url=str(raw.url),
+            headers={k.lower(): v or "" for k, v in raw.headers.items()},
+            text=raw.text,
+        )
+        _raise_for(response)
+        return response
+
+    async def get_json(self, url: str, **kwargs: Any) -> Any:
+        return (await self.call("GET", url, **kwargs)).json()
+
+    async def post_json(self, url: str, payload: Any, **kwargs: Any) -> Any:
+        return (await self.call("POST", url, json=payload, **kwargs)).json()
+
+    async def cache_get(self, key: str) -> str | None:
+        """Short-lived app data (a build id, a page token), kept in this process."""
+        entry = self._cache.get(key)
+        if entry is None or entry[0] < time.monotonic():
+            return None
+        return entry[1]
+
+    async def cache_set(self, key: str, value: str, ttl_s: int) -> None:
+        self._cache[key] = (time.monotonic() + ttl_s, value)
+
+    async def close(self) -> None:
+        if self._http is not None:
+            await self._http.close()
+            self._http = None