docs: add Python examples for the hub, a node and its control API

examples/ holds small scripts that talk to MeshBay the way the application
does, with the values to change as variables at the top of each one:

- meshbay_session.py: hub sign-in, WebRTC to a node serving the group, and
  the handshake (identity bundle, group key, proofs both ways)
- list_groups.py: the user's groups, up or down
- download.py: one file, decrypted chunk by chunk under a transfer lease
- upload.py: one file, sealed in 48 KiB chunks into a group folder
- create_group.py: creates a group on the hub and hosts it on the local node
  through its loopback control API

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 31 insertions, 0 deletions

diff --git a/examples/list_groups.py b/examples/list_groups.py
new file mode 100644
index 0000000..61773e2
--- /dev/null
+++ b/examples/list_groups.py
@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""List a user's groups, and whether a node serving each one is up."""
+
+import sys
+
+import httpx
+from meshbay_session import auth_key
+
+HUB = "https://meshbay.org"
+USERNAME = "alice"
+PASSPHRASE = "your passphrase"
+
+
+def main() -> None:
+    with httpx.Client(base_url=HUB, timeout=30) as hub:
+        r = hub.post("/v1/users/login",
+                     json={"username": USERNAME, "auth_key": auth_key(USERNAME, PASSPHRASE)})
+        if r.status_code != 200:
+            sys.exit(f"Sign-in refused: {r.text}")
+        auth = {"Authorization": f"Bearer {r.json()['access_token']}"}
+        groups = hub.get("/v1/groups/mine", headers=auth).json()["groups"]
+
+    # "up" means a node serving the group is connected to the hub right now.
+    # It does not prove that this machine can reach that node.
+    for g in groups:
+        state = "up" if g["node_online"] else "down"
+        print(f"{state:<6}{g['name']}  (@{g['owner_username']})")
+
+
+if __name__ == "__main__":
+    main()