pingwa 0.2.0__tar.gz

pingwa-0.2.0/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 pingwa contributors
+
+Scope: this license covers the pingwa CLIENT only — the source under
+`src/pingwa/client/` (the `pingwa` package published to PyPI: the CLI, the HTTP
+client, and the stdio MCP server). The pingwa server (API, worker, billing,
+webhooks, registrations and related modules) is NOT covered by this license and
+is not published; all rights to it are reserved by the operator.
+
+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.

pingwa-0.2.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: pingwa
+Version: 0.2.0
+Summary: WhatsApp notifications + human-in-the-loop for AI agents and scripts — curl to WhatsApp in 60s, no app, no dashboard.
+Keywords: whatsapp,notifications,mcp,agent,cli,llm,ai,human-in-the-loop
+Author: grzgrzgrz3
+Author-email: grzgrzgrz3 <grzgrzgrz3@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp>=1.2.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://pingwa.dev
+Project-URL: Documentation, https://pingwa.dev/llms.txt
+Project-URL: Source, https://github.com/grzgrzgrz3/pingwa-client
+Description-Content-Type: text/markdown
+
+# pingwa (client)
+
+WhatsApp notifications + human-in-the-loop for AI agents and scripts — from your
+terminal or an MCP client. `curl → WhatsApp in 60s`, no app, no dashboard.
+
+This is the **open-source (MIT) pingwa client**: a CLI, a tiny HTTP client, and an
+MCP server. It talks to a pingwa backend (the hosted service at
+`https://pingwa.dev`, or your own). The backend is separate and private;
+this client is not.
+
+## Install & use
+
+No install needed with [uv](https://docs.astral.sh/uv/):
+
+```bash
+export PINGWA_KEY=pw_your_key          # get one: send "join" on WhatsApp to the service number
+uvx pingwa send "build finished ✅"     # notify your own phone
+echo "deploy done" | uvx pingwa send -  # from stdin
+uvx pingwa ask "Deploy to prod?" --button yes --button no   # wait for a reply from your phone
+uvx pingwa replies                      # pull messages your phone sent back (out-of-band steering)
+uvx pingwa me                           # plan / quota / reply-window
+uvx pingwa upgrade                      # get a Stripe link to go Pro (no password needed)
+uvx pingwa send "x" --json              # raw JSON response
+```
+
+Exit codes: `0` ok · `2` missing key · `3` quota exceeded · `1` other.
+Override the backend with `PINGWA_BASE_URL` or `--base-url`.
+
+## MCP server
+
+Same tools on stdio and remote: `notify(text)`, `ask(text, buttons?, timeout?)`,
+`check_replies(since?, wait?)`, `check_status()`, `upgrade()`.
+
+Local (stdio) — for Claude Desktop / Claude Code:
+
+```json
+{"mcpServers":{"pingwa":{"command":"uvx","args":["pingwa","mcp"],
+ "env":{"PINGWA_KEY":"pw_your_key"}}}}
+```
+
+Remote (Streamable HTTP, no install):
+
+```json
+{"mcpServers":{"pingwa":{"url":"https://pingwa.dev/mcp",
+ "headers":{"Authorization":"Bearer pw_your_key"}}}}
+```
+
+Every error carries an `action` hint, so an agent knows what to do next.
+
+## What it sends
+
+Only your message text and your key, to the pingwa backend you point it at — over
+HTTPS. Nothing else. The recipient is always your own phone (there is no "to"
+field). See the service's [/privacy](https://pingwa.dev/privacy).
+
+## Repository
+
+The client is developed in a private monorepo next to the (proprietary) backend;
+[grzgrzgrz3/pingwa-client](https://github.com/grzgrzgrz3/pingwa-client) is its
+public read-only mirror — the full source of every published `pingwa` release,
+synced on release. Issues and PRs are welcome there.
+
+## License
+
+MIT — see the `LICENSE` in the repository root. Covers this client package only.

pingwa-0.2.0/pyproject.toml

@@ -0,0 +1,79 @@
+[project]
+name = "pingwa"
+version = "0.2.0"
+description = "WhatsApp notifications + human-in-the-loop for AI agents and scripts — curl to WhatsApp in 60s, no app, no dashboard."
+# Client-facing readme (the published wheel is client-only). The repo root README.md
+# is the private ops/deploy manual (homelab IPs, ssh targets) — MUST NOT ship to PyPI.
+readme = "src/pingwa/client/README.md"
+authors = [
+    { name = "grzgrzgrz3", email = "grzgrzgrz3@gmail.com" }
+]
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["whatsapp", "notifications", "mcp", "agent", "cli", "llm", "ai", "human-in-the-loop"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications :: Chat",
+    "Topic :: Software Development :: Libraries",
+]
+# Client-only core: keeps `uvx pingwa` ultralight. Heavy server deps live in the
+# `server` dependency-group (below) and are never part of the published wheel.
+dependencies = [
+    "httpx>=0.28.1",
+    "mcp>=1.2.0",
+]
+
+[project.urls]
+Homepage = "https://pingwa.dev"
+Documentation = "https://pingwa.dev/llms.txt"
+Source = "https://github.com/grzgrzgrz3/pingwa-client"
+
+[project.scripts]
+pingwa = "pingwa.client.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.28,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# Publish the CLIENT only. The proprietary server lives in the sibling package
+# `src/pingwa_server/` which this backend never touches (module-name below), so
+# both published artifacts (wheel AND sdist) are client-only by construction —
+# no exclude lists. tests/test_packaging.py inspects the built artifacts.
+module-name = "pingwa"
+module-root = "src"
+
+[dependency-groups]
+# Server runtime — dev/Docker only, excluded from the published wheel (PEP 735).
+server = [
+    "argon2-cffi>=25.1.0",
+    "arq>=0.28.0",
+    "asyncpg>=0.31.0",
+    "fastapi>=0.139.0",
+    "prometheus-client>=0.25.0",
+    "prometheus-fastapi-instrumentator>=8.0.2",
+    "pydantic-settings>=2.14.2",
+    "pyjwt>=2.13.0",
+    "segno>=1.6.6",
+    "sqlalchemy[asyncio]>=2.0.51",
+    "uvicorn[standard]>=0.51.0",
+]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "pyyaml>=6.0.3",
+    "respx>=0.23.1",
+    "ruff>=0.15.21",
+]
+
+[tool.uv]
+# `uv sync` (dev) installs both; Dockerfile's `--no-dev` keeps server, drops dev.
+default-groups = ["dev", "server"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "session"
+asyncio_default_test_loop_scope = "session"

pingwa-0.2.0/src/pingwa/client/README.md

@@ -0,0 +1,65 @@
+# pingwa (client)
+
+WhatsApp notifications + human-in-the-loop for AI agents and scripts — from your
+terminal or an MCP client. `curl → WhatsApp in 60s`, no app, no dashboard.
+
+This is the **open-source (MIT) pingwa client**: a CLI, a tiny HTTP client, and an
+MCP server. It talks to a pingwa backend (the hosted service at
+`https://pingwa.dev`, or your own). The backend is separate and private;
+this client is not.
+
+## Install & use
+
+No install needed with [uv](https://docs.astral.sh/uv/):
+
+```bash
+export PINGWA_KEY=pw_your_key          # get one: send "join" on WhatsApp to the service number
+uvx pingwa send "build finished ✅"     # notify your own phone
+echo "deploy done" | uvx pingwa send -  # from stdin
+uvx pingwa ask "Deploy to prod?" --button yes --button no   # wait for a reply from your phone
+uvx pingwa replies                      # pull messages your phone sent back (out-of-band steering)
+uvx pingwa me                           # plan / quota / reply-window
+uvx pingwa upgrade                      # get a Stripe link to go Pro (no password needed)
+uvx pingwa send "x" --json              # raw JSON response
+```
+
+Exit codes: `0` ok · `2` missing key · `3` quota exceeded · `1` other.
+Override the backend with `PINGWA_BASE_URL` or `--base-url`.
+
+## MCP server
+
+Same tools on stdio and remote: `notify(text)`, `ask(text, buttons?, timeout?)`,
+`check_replies(since?, wait?)`, `check_status()`, `upgrade()`.
+
+Local (stdio) — for Claude Desktop / Claude Code:
+
+```json
+{"mcpServers":{"pingwa":{"command":"uvx","args":["pingwa","mcp"],
+ "env":{"PINGWA_KEY":"pw_your_key"}}}}
+```
+
+Remote (Streamable HTTP, no install):
+
+```json
+{"mcpServers":{"pingwa":{"url":"https://pingwa.dev/mcp",
+ "headers":{"Authorization":"Bearer pw_your_key"}}}}
+```
+
+Every error carries an `action` hint, so an agent knows what to do next.
+
+## What it sends
+
+Only your message text and your key, to the pingwa backend you point it at — over
+HTTPS. Nothing else. The recipient is always your own phone (there is no "to"
+field). See the service's [/privacy](https://pingwa.dev/privacy).
+
+## Repository
+
+The client is developed in a private monorepo next to the (proprietary) backend;
+[grzgrzgrz3/pingwa-client](https://github.com/grzgrzgrz3/pingwa-client) is its
+public read-only mirror — the full source of every published `pingwa` release,
+synced on release. Issues and PRs are welcome there.
+
+## License
+
+MIT — see the `LICENSE` in the repository root. Covers this client package only.

pingwa-0.2.0/src/pingwa/client/__init__.py

@@ -0,0 +1,13 @@
+"""pingwa client — the open-source (MIT) half of pingwa.
+
+This package (`pingwa.client`) is the ONLY code shipped in the published `pingwa`
+wheel's public surface: the CLI (`pingwa`), the HTTP client, the shared tool layer,
+and the stdio MCP server. It depends on nothing but httpx + the MCP SDK and never
+imports a server module, so `uvx pingwa` stays tiny and auditable.
+
+Licensing boundary: everything under this package is MIT-licensed (see repo LICENSE).
+The pingwa server (api, worker, billing, webhooks, registrations, …) that lives
+elsewhere in the repo is proprietary and not published. Keep this package free of
+server imports so the boundary — and the trust claim "the client is open source" —
+stays true.
+"""

pingwa-0.2.0/src/pingwa/client/cli.py

@@ -0,0 +1,152 @@
+"""`pingwa` command-line interface.
+
+Commands: send, me, mcp. Reads PINGWA_KEY (and optional PINGWA_BASE_URL) from the
+environment. CI-friendly: non-zero exit on failure, actionable message on stderr.
+"""
+import argparse
+import json as jsonlib
+import sys
+from importlib.metadata import PackageNotFoundError, version
+
+from pingwa.client import tools
+from pingwa.client.http import MissingKeyError, PingwaClient, PingwaError
+
+EXIT_OK = 0
+EXIT_ERR = 1
+EXIT_MISSING_KEY = 2
+EXIT_QUOTA = 3
+
+
+def _version() -> str:
+    try:
+        return version("pingwa")
+    except PackageNotFoundError:
+        return "unknown"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="pingwa",
+        description="WhatsApp notifications for AI agents & scripts. "
+                    "Set PINGWA_KEY (a pw_... key from sending 'join' on WhatsApp).")
+    p.add_argument("--version", action="version", version=f"pingwa {_version()}")
+    p.add_argument("--base-url", default=None,
+                   help="API base URL (default: $PINGWA_BASE_URL or the pingwa cloud)")
+    sub = p.add_subparsers(dest="command")
+
+    s = sub.add_parser("send", help="send a WhatsApp notification to your own phone")
+    s.add_argument("text", nargs="?", help="message text; omit or pass '-' to read stdin")
+    s.add_argument("--image-url", dest="image_url", default=None, metavar="URL",
+                   help="public https image URL to attach (shown with the text as caption; "
+                        "delivered as an image only inside your open 24h window)")
+    s.add_argument("--json", action="store_true", help="print the raw JSON response")
+
+    a = sub.add_parser("ask", help="ask your phone a question and wait for the reply (free text or a button)")
+    a.add_argument("text", nargs="?", help="the question; omit or pass '-' to read stdin")
+    a.add_argument("--button", action="append", dest="buttons", metavar="TITLE",
+                   help="add a tappable reply button (repeatable, up to 3); omit for a free-text answer")
+    a.add_argument("--timeout", type=int, default=60, help="seconds to wait for the human (max 90)")
+    a.add_argument("--json", action="store_true", help="print the raw JSON response")
+
+    r = sub.add_parser("replies", help="pull inbound WhatsApp messages your phone sent (out-of-band instructions)")
+    r.add_argument("--since", default=None, help="cursor from a previous call — only newer messages")
+    r.add_argument("--wait", type=int, default=0, help="long-poll up to N seconds for a new message")
+    r.add_argument("--json", action="store_true", help="print the raw JSON response")
+
+    m = sub.add_parser("me", help="show plan, quota and reply-window status")
+    m.add_argument("--json", action="store_true", help="print the raw JSON response")
+
+    u = sub.add_parser("upgrade", help="get a Stripe link to upgrade to Pro (or manage an existing Pro sub)")
+    u.add_argument("--json", action="store_true", help="print the raw JSON response")
+
+    sub.add_parser("mcp", help="run the pingwa MCP server over stdio (Claude Desktop/Code)")
+    return p
+
+
+def _client(args) -> PingwaClient:
+    return PingwaClient.from_env(base_url=args.base_url)
+
+
+def _cmd_send(args) -> int:
+    text = args.text
+    if text is None or text == "-":
+        text = sys.stdin.read()
+    client = _client(args)
+    if args.json:
+        print(jsonlib.dumps(client.notify(text.strip(), args.image_url)))
+    else:
+        print(tools.notify_tool(client, text, args.image_url))
+    return EXIT_OK
+
+
+def _cmd_ask(args) -> int:
+    text = args.text
+    if text is None or text == "-":
+        text = sys.stdin.read()
+    client = _client(args)
+    if args.json:
+        try:
+            print(jsonlib.dumps(client.ask(text.strip(), args.buttons, args.timeout)))
+        except PingwaError as exc:
+            if exc.status == 408:  # timeout is normal flow: question delivered, no answer yet
+                print(jsonlib.dumps({"answered": False, "error": exc.code, "message": exc.message}))
+                return EXIT_OK
+            raise
+    else:
+        print(tools.ask_tool(client, text, args.buttons, args.timeout))
+    return EXIT_OK
+
+
+def _cmd_replies(args) -> int:
+    client = _client(args)
+    if args.json:
+        print(jsonlib.dumps(client.check_replies(args.since, args.wait)))
+    else:
+        print(tools.check_replies_tool(client, args.since, args.wait))
+    return EXIT_OK
+
+
+def _cmd_me(args) -> int:
+    client = _client(args)
+    if args.json:
+        print(jsonlib.dumps(client.me()))
+    else:
+        print(tools.status_tool(client))
+    return EXIT_OK
+
+
+def _cmd_upgrade(args) -> int:
+    client = _client(args)
+    if args.json:
+        print(jsonlib.dumps(client.upgrade()))
+    else:
+        print(tools.upgrade_tool(client))
+    return EXIT_OK
+
+
+def _cmd_mcp(args) -> int:
+    from pingwa.client.mcp_stdio import main as mcp_main
+    mcp_main()
+    return EXIT_OK
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help(sys.stderr)
+        return EXIT_ERR
+    handlers = {"send": _cmd_send, "ask": _cmd_ask, "replies": _cmd_replies,
+                "me": _cmd_me, "upgrade": _cmd_upgrade, "mcp": _cmd_mcp}
+    try:
+        return handlers[args.command](args)
+    except MissingKeyError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_MISSING_KEY
+    except PingwaError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_QUOTA if exc.status == 402 else EXIT_ERR
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

pingwa-0.2.0/src/pingwa/client/http.py

@@ -0,0 +1,201 @@
+"""Tiny synchronous pingwa REST client — the shared core of the CLI and both MCP
+transports. Imports only httpx + stdlib so `uvx pingwa` stays ultralight and the
+client works without any server dependency installed.
+
+Every error is raised as a PingwaError carrying the server's self-describing
+`action` string verbatim, so an agent reading the message knows what to do next.
+"""
+import os
+from urllib.parse import urlencode
+
+import httpx
+
+DEFAULT_BASE_URL = "https://pingwa.dev"
+ENV_KEY = "PINGWA_KEY"
+ENV_BASE = "PINGWA_BASE_URL"
+
+
+class PingwaError(Exception):
+    def __init__(self, message: str, *, code: str | None = None,
+                 action: str | None = None, status: int | None = None):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.action = action
+        self.status = status
+
+    def __str__(self) -> str:
+        return f"{self.message}  → {self.action}" if self.action else self.message
+
+
+class MissingKeyError(PingwaError):
+    def __init__(self) -> None:
+        super().__init__(
+            "No pingwa API key. Set the PINGWA_KEY environment variable (a pw_... key).",
+            code="missing_key",
+            action=("Send 'join' on WhatsApp to the pingwa service number to get a key, "
+                    "then export PINGWA_KEY=pw_..."),
+        )
+
+
+class PingwaClient:
+    def __init__(self, key: str, base_url: str = DEFAULT_BASE_URL, *, timeout: float = 30.0):
+        self.key = key
+        self.base_url = base_url.rstrip("/")
+        self._timeout = timeout
+
+    @classmethod
+    def from_env(cls, base_url: str | None = None) -> "PingwaClient":
+        key = os.environ.get(ENV_KEY, "").strip()
+        if not key:
+            raise MissingKeyError()
+        base = base_url or os.environ.get(ENV_BASE) or DEFAULT_BASE_URL
+        return cls(key, base)
+
+    def _request(self, method: str, path: str, json: dict | None = None,
+                 *, timeout: float | None = None) -> dict:
+        url = self.base_url + path
+        headers = {"Authorization": f"Bearer {self.key}"}
+        try:
+            r = httpx.request(method, url, json=json, headers=headers,
+                              timeout=timeout or self._timeout)
+        except httpx.HTTPError as exc:
+            raise PingwaError(
+                f"Cannot reach pingwa at {self.base_url}: {exc}",
+                code="network_error",
+                action="Check your network or PINGWA_BASE_URL, then retry.",
+            ) from exc
+        return _parse(r)
+
+    def notify(self, text: str, image_url: str | None = None) -> dict:
+        return self._request("POST", "/v1/notify", _notify_body(text, image_url))
+
+    def me(self) -> dict:
+        return self._request("GET", "/v1/me")
+
+    def ask(self, text: str, buttons: list[str] | None = None, timeout: int = 60) -> dict:
+        """Send a question and block until the human replies on WhatsApp (free text
+        or a button tap) or `timeout` seconds pass. On timeout the server raises a
+        408 (code 'ask_timeout') — the question was still delivered and the answer
+        stays retrievable via check_replies. The HTTP read timeout is set above the
+        server's long-poll so the wait completes client-side."""
+        return self._request("POST", "/v1/ask", _ask_body(text, buttons, timeout),
+                             timeout=timeout + 15)
+
+    def check_replies(self, since: str | None = None, wait: int = 0) -> dict:
+        """Inbound WhatsApp messages after the `since` cursor (long-poll up to `wait`
+        seconds). Returns {messages, cursor}; pass the cursor back as `since` next time."""
+        return self._request("GET", _inbox_path(since, wait),
+                             timeout=(wait + 15) if wait else None)
+
+    def upgrade(self) -> dict:
+        """Return a billing link: a Stripe Checkout URL to start Pro, or — if the
+        account is already Pro — a billing-portal URL to manage/cancel. The api_key
+        alone authorizes this; the human only enters payment on Stripe's page."""
+        try:
+            res = self._request("POST", "/v1/billing/checkout")
+            return {"url": res["url"], "kind": "checkout"}
+        except PingwaError as exc:
+            if exc.code == "already_pro":
+                res = self._request("POST", "/v1/billing/portal")
+                return {"url": res["url"], "kind": "portal"}
+            raise
+
+
+class AsyncPingwaClient:
+    """Async twin of PingwaClient, for callers already on an event loop (the remote
+    MCP server, which calls the REST API over loopback — a sync client there would
+    block the single event loop and deadlock the self-call)."""
+
+    def __init__(self, key: str, base_url: str = DEFAULT_BASE_URL, *, timeout: float = 30.0):
+        self.key = key
+        self.base_url = base_url.rstrip("/")
+        self._timeout = timeout
+
+    async def _request(self, method: str, path: str, json: dict | None = None,
+                       *, timeout: float | None = None) -> dict:
+        headers = {"Authorization": f"Bearer {self.key}"}
+        try:
+            async with httpx.AsyncClient(timeout=timeout or self._timeout) as client:
+                r = await client.request(method, self.base_url + path, json=json, headers=headers)
+        except httpx.HTTPError as exc:
+            raise PingwaError(
+                f"Cannot reach pingwa at {self.base_url}: {exc}",
+                code="network_error",
+                action="Check your network or PINGWA_BASE_URL, then retry.",
+            ) from exc
+        return _parse(r)
+
+    async def notify(self, text: str, image_url: str | None = None) -> dict:
+        return await self._request("POST", "/v1/notify", _notify_body(text, image_url))
+
+    async def me(self) -> dict:
+        return await self._request("GET", "/v1/me")
+
+    async def ask(self, text: str, buttons: list[str] | None = None, timeout: int = 60) -> dict:
+        """Async twin of PingwaClient.ask."""
+        return await self._request("POST", "/v1/ask", _ask_body(text, buttons, timeout),
+                                   timeout=timeout + 15)
+
+    async def check_replies(self, since: str | None = None, wait: int = 0) -> dict:
+        """Async twin of PingwaClient.check_replies."""
+        return await self._request("GET", _inbox_path(since, wait),
+                                   timeout=(wait + 15) if wait else None)
+
+    async def upgrade(self) -> dict:
+        """Async twin of PingwaClient.upgrade."""
+        try:
+            res = await self._request("POST", "/v1/billing/checkout")
+            return {"url": res["url"], "kind": "checkout"}
+        except PingwaError as exc:
+            if exc.code == "already_pro":
+                res = await self._request("POST", "/v1/billing/portal")
+                return {"url": res["url"], "kind": "portal"}
+            raise
+
+
+def _notify_body(text: str, image_url: str | None) -> dict:
+    body: dict = {"text": text}
+    if image_url:
+        body["image_url"] = image_url
+    return body
+
+
+def _ask_body(text: str, buttons: list[str] | None, timeout: int) -> dict:
+    body: dict = {"text": text, "timeout": timeout}
+    if buttons:
+        body["buttons"] = buttons
+    return body
+
+
+def _inbox_path(since: str | None, wait: int) -> str:
+    params = {}
+    if since:
+        params["since"] = since
+    if wait:
+        params["wait"] = wait
+    return "/v1/inbox" + (("?" + urlencode(params)) if params else "")
+
+
+def _parse(r: httpx.Response) -> dict:
+    # 2xx only: redirects are not followed, so a 3xx here means a misconfigured
+    # base URL — falling through reports it instead of faking an empty success.
+    if r.is_success:
+        try:
+            return r.json()
+        except ValueError:
+            return {}
+    detail: object = r.text
+    try:
+        body = r.json()
+        detail = body.get("detail", body) if isinstance(body, dict) else body
+    except ValueError:
+        pass
+    if isinstance(detail, dict):
+        raise PingwaError(
+            detail.get("message") or detail.get("error") or f"HTTP {r.status_code}",
+            code=detail.get("error"), action=detail.get("action"), status=r.status_code)
+    if isinstance(detail, list):  # FastAPI 422 validation errors
+        msgs = "; ".join(str(e.get("msg", e)) for e in detail)
+        raise PingwaError(f"Invalid request: {msgs}", code="validation_error", status=r.status_code)
+    raise PingwaError(str(detail) or f"HTTP {r.status_code}", status=r.status_code)

pingwa-0.2.0/src/pingwa/client/mcp_stdio.py

@@ -0,0 +1,98 @@
+"""pingwa MCP server over stdio — for Claude Desktop / Claude Code and any
+stdio MCP client. Run via `pingwa mcp`. Authenticates with PINGWA_KEY from the
+environment.
+
+Tool contract (frozen — tools are added, never renamed/changed):
+notify, check_status, upgrade, ask, check_replies.
+"""
+from mcp.server.fastmcp import FastMCP
+
+from pingwa.client import tools
+from pingwa.client.http import PingwaClient
+
+INSTRUCTIONS = (
+    "pingwa is a two-way WhatsApp bridge to the account owner's own phone — a human in "
+    "the loop for AI agents. There is no recipient field; messages always go to the key "
+    "owner. Use `notify` to tell the human something happened (build done, task finished). "
+    "Use `ask` to ask a question and BLOCK until the human answers on WhatsApp — they can "
+    "reply with free text (steer you: 'use the other API', 'ship it') or tap one of up to "
+    "3 buttons; the reply comes back to you. Use `check_replies` to pull any inbound "
+    "WhatsApp messages the human sent (poll for out-of-band instructions). Use "
+    "`check_status` to see plan and remaining quota, and `upgrade` when quota runs out to "
+    "get a Stripe link for the human to open (no password needed). "
+    "Set PINGWA_KEY (a pw_... key) in the environment; without it, tools return an "
+    "actionable error explaining how to get one."
+)
+
+
+def register_tools(mcp: FastMCP, get_client) -> FastMCP:
+    """Attach the frozen pingwa tool set to `mcp`. `get_client()` is called per
+    invocation to obtain a PingwaClient — from the env (stdio) or the request's
+    Authorization header (remote). Shared by both transports so the tool contract
+    is defined exactly once."""
+
+    @mcp.tool()
+    def notify(text: str, image_url: str | None = None) -> str:
+        """Send a WhatsApp notification to the account owner's own phone.
+
+        `text` is the message (1-1024 chars). `image_url` (optional) is a public https
+        image link — a screenshot, chart or diff — delivered as an image with `text` as
+        the caption when the user's 24h window is open (otherwise text only). Returns a
+        confirmation with the queued message id; raises an actionable error on quota/auth.
+        """
+        return tools.notify_tool(get_client(), text, image_url)
+
+    @mcp.tool(name="check_status")
+    def check_status() -> str:
+        """Show the pingwa account's plan, remaining monthly quota, and whether the
+        free 24h WhatsApp reply window is currently open."""
+        return tools.status_tool(get_client())
+
+    @mcp.tool()
+    def upgrade() -> str:
+        """Get a link to upgrade the account to Pro (raises the monthly quota).
+
+        Returns a Stripe Checkout URL for the human to open and pay — no pingwa
+        password needed, the card is handled by Stripe. If the account is already
+        Pro, returns a billing-portal URL to manage or cancel instead.
+        """
+        return tools.upgrade_tool(get_client())
+
+    @mcp.tool()
+    def ask(text: str, buttons: list[str] | None = None, timeout: int = 60) -> str:
+        """Ask the human a question on WhatsApp and BLOCK until they reply (or timeout).
+
+        `text` is the question. `buttons` (optional, up to 3) render as tappable reply
+        buttons; omit them to invite a free-text answer the human types on their phone —
+        use this to let the human steer you mid-task. `timeout` is seconds to wait
+        (max 90). Returns the human's reply (free text and/or the chosen option). On
+        timeout, returns a note — the question was delivered and the answer is still
+        retrievable via `check_replies`.
+        """
+        return tools.ask_tool(get_client(), text, buttons, timeout)
+
+    @mcp.tool(name="check_replies")
+    def check_replies(since: str | None = None, wait: int = 0) -> str:
+        """Pull inbound WhatsApp messages the human sent to pingwa (out-of-band
+        instructions, or late answers to an `ask`). `since` is a cursor from a previous
+        call (pass it back to get only newer messages); `wait` long-polls up to that many
+        seconds for something to arrive. Returns the messages and a new cursor.
+        """
+        return tools.check_replies_tool(get_client(), since, wait)
+
+    return mcp
+
+
+def build_server(client_factory=PingwaClient.from_env) -> FastMCP:
+    """FastMCP instance with the pingwa tools. `client_factory` is called per tool
+    invocation to build the REST client (default: read PINGWA_KEY from the env);
+    tests inject a factory returning a mocked client."""
+    return register_tools(FastMCP("pingwa", instructions=INSTRUCTIONS), client_factory)
+
+
+def main() -> None:
+    build_server().run()  # stdio transport (default)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

pingwa-0.2.0/src/pingwa/client/tools.py

@@ -0,0 +1,117 @@
+"""Tool logic shared by the CLI and both MCP transports (stdio + remote).
+
+Each function returns an agent/human-readable string; errors propagate as
+PingwaError (message + actionable hint). Sync and async variants share the same
+validation and formatting, so behaviour is identical across surfaces.
+"""
+from pingwa.client.http import PingwaError
+
+
+def _validate_text(text: str) -> str:
+    text = (text or "").strip()
+    if not text:
+        raise PingwaError(
+            "Notification text is empty.",
+            code="empty_text",
+            action="Pass a non-empty message, e.g. notify(text='build finished').",
+        )
+    return text
+
+
+def _fmt_notify(res: dict) -> str:
+    return (f"Sent ✓ — WhatsApp notification queued "
+            f"(id={res.get('id')}, billing={res.get('billing_class')}, "
+            f"status={res.get('status')}).")
+
+
+def _fmt_status(me: dict) -> str:
+    usage = me.get("usage") or {}
+    return (f"plan={me.get('plan')} active={me.get('active')} "
+            f"window_open={me.get('window_open')} "
+            f"quota_used={usage.get('paid_used')}/{usage.get('paid_quota')}")
+
+
+def _fmt_upgrade(res: dict) -> str:
+    url = res.get("url")
+    if res.get("kind") == "portal":
+        return f"Already on Pro. Manage or cancel your subscription here: {url}"
+    return ("Upgrade to Pro — open this link to pay "
+            f"(card handled by Stripe, never by pingwa): {url}")
+
+
+def _fmt_reply(res: dict) -> str:
+    reply = res.get("reply") or {}
+    text = (reply.get("text") or "").strip()
+    button = reply.get("button_id")
+    line = f"Human replied: {text or '(empty)'}"
+    if button:
+        line += f"  [chosen option: {button}]"
+    return line
+
+
+def _fmt_timeout(err: PingwaError) -> str:
+    """A 408 from /v1/ask is normal flow, not a failure: the question was delivered,
+    the human just hasn't answered yet. Return the actionable note instead of raising
+    so an agent tool call resolves cleanly."""
+    return f"No reply yet — {err.message} {err.action or ''}".strip()
+
+
+def _fmt_replies(res: dict) -> str:
+    msgs = res.get("messages") or []
+    cursor = res.get("cursor")
+    if not msgs:
+        return f"No new replies. (cursor={cursor})"
+    lines = [f"- {m.get('body', '').strip()}"
+             + (f"  [option: {m['button_id']}]" if m.get("button_id") else "")
+             for m in msgs]
+    return f"{len(msgs)} reply(ies):\n" + "\n".join(lines) + f"\n(cursor={cursor})"
+
+
+def notify_tool(client, text: str, image_url: str | None = None) -> str:
+    return _fmt_notify(client.notify(_validate_text(text), image_url))
+
+
+def status_tool(client) -> str:
+    return _fmt_status(client.me())
+
+
+def upgrade_tool(client) -> str:
+    return _fmt_upgrade(client.upgrade())
+
+
+def ask_tool(client, text: str, buttons: list[str] | None = None, timeout: int = 60) -> str:
+    try:
+        return _fmt_reply(client.ask(_validate_text(text), buttons, timeout))
+    except PingwaError as exc:
+        if exc.status == 408:
+            return _fmt_timeout(exc)
+        raise
+
+
+def check_replies_tool(client, since: str | None = None, wait: int = 0) -> str:
+    return _fmt_replies(client.check_replies(since, wait))
+
+
+async def notify_tool_async(client, text: str, image_url: str | None = None) -> str:
+    return _fmt_notify(await client.notify(_validate_text(text), image_url))
+
+
+async def status_tool_async(client) -> str:
+    return _fmt_status(await client.me())
+
+
+async def upgrade_tool_async(client) -> str:
+    return _fmt_upgrade(await client.upgrade())
+
+
+async def ask_tool_async(client, text: str, buttons: list[str] | None = None, timeout: int = 60) -> str:
+    try:
+        return _fmt_reply(await client.ask(_validate_text(text), buttons, timeout))
+    except PingwaError as exc:
+        if exc.status == 408:
+            return _fmt_timeout(exc)
+        raise
+
+
+async def check_replies_tool_async(client, since: str | None = None, wait: int = 0) -> str:
+    return _fmt_replies(await client.check_replies(since, wait))