buzzkit 0.1.3__cp312-abi3-win_amd64.whl

buzzkit/__init__.py

@@ -0,0 +1,92 @@
+"""buzzkit — Python bindings + async client for Block's Buzz (Nostr) protocol.
+
+Low-level event building/signing/verification is done in Rust (``buzz-core`` /
+``buzz-sdk``); all network I/O is pure Python. Use the module-level functions for
+one-off event work, or :class:`BuzzClient` for a managed async relay connection.
+
+This is an independent, unofficial project — not affiliated with Block, Inc.
+"""
+
+from __future__ import annotations
+
+from ._native import (
+    HUDDLE_FRAME_SAMPLES,
+    HUDDLE_PROTOCOL_VERSION,
+    HUDDLE_SAMPLE_RATE,
+    KIND_ADD_MEMBER,
+    KIND_AUTH,
+    KIND_CREATE_CHANNEL,
+    KIND_HTTP_AUTH,
+    KIND_HUDDLE_ENDED,
+    KIND_HUDDLE_PARTICIPANT_JOINED,
+    KIND_HUDDLE_PARTICIPANT_LEFT,
+    KIND_HUDDLE_STARTED,
+    KIND_PRESENCE_UPDATE,
+    KIND_REACTION,
+    KIND_STREAM_MESSAGE,
+    KIND_STREAM_MESSAGE_V2,
+    HuddleDecoder,
+    HuddleEncoder,
+    build_auth_event,
+    build_create_channel_event,
+    build_huddle_started_event,
+    build_join_channel_event,
+    build_message_event,
+    build_presence_event,
+    build_profile_event,
+    compute_auth_tag,
+    generate_keypair,
+    pubkey_from_secret,
+    sign_nip98,
+    verify_event,
+)
+from .client import BuzzClient
+from .huddle import (
+    HuddleAudio,
+    HuddleClient,
+    HuddleError,
+    HuddleEvent,
+    HuddlePeerJoined,
+    HuddlePeerLeft,
+)
+
+__version__ = "0.1.3"
+
+__all__ = [
+    "HUDDLE_FRAME_SAMPLES",
+    "HUDDLE_PROTOCOL_VERSION",
+    "HUDDLE_SAMPLE_RATE",
+    "KIND_ADD_MEMBER",
+    "KIND_AUTH",
+    "KIND_CREATE_CHANNEL",
+    "KIND_HTTP_AUTH",
+    "KIND_HUDDLE_ENDED",
+    "KIND_HUDDLE_PARTICIPANT_JOINED",
+    "KIND_HUDDLE_PARTICIPANT_LEFT",
+    "KIND_HUDDLE_STARTED",
+    "KIND_PRESENCE_UPDATE",
+    "KIND_REACTION",
+    "KIND_STREAM_MESSAGE",
+    "KIND_STREAM_MESSAGE_V2",
+    "BuzzClient",
+    "HuddleAudio",
+    "HuddleClient",
+    "HuddleDecoder",
+    "HuddleEncoder",
+    "HuddleError",
+    "HuddleEvent",
+    "HuddlePeerJoined",
+    "HuddlePeerLeft",
+    "build_auth_event",
+    "build_create_channel_event",
+    "build_huddle_started_event",
+    "build_join_channel_event",
+    "build_message_event",
+    "build_presence_event",
+    "build_profile_event",
+    "compute_auth_tag",
+    "generate_keypair",
+    "pubkey_from_secret",
+    "sign_nip98",
+    "verify_event",
+]

buzzkit/_native.pyi

@@ -0,0 +1,102 @@
+"""Type stubs for the Rust extension module (buzzkit._native)."""
+
+def generate_keypair() -> tuple[str, str, str]:
+    """Return ``(nsec, npub, pubkey_hex)`` for a fresh keypair."""
+
+def pubkey_from_secret(secret: str) -> tuple[str, str]:
+    """Return ``(npub, pubkey_hex)`` for a secret (hex or ``nsec…``)."""
+
+def build_message_event(
+    secret: str, channel_id: str, content: str, mentions: list[str] | None = ...
+) -> str:
+    """Build + sign a channel message (kind 9); returns NIP-01 event JSON."""
+
+def build_profile_event(
+    secret: str,
+    display_name: str | None = ...,
+    name: str | None = ...,
+    about: str | None = ...,
+    picture: str | None = ...,
+    nip05: str | None = ...,
+    auth_tag: str | None = ...,
+) -> str:
+    """Build + sign a profile event (kind 0); returns NIP-01 event JSON.
+
+    ``auth_tag`` embeds a NIP-OA owner attestation so the Buzz desktop shows
+    the identity as "managed by <owner>".
+    """
+
+def build_join_channel_event(secret: str, channel_id: str) -> str:
+    """Build + sign a NIP-29 channel self-join event (kind 9000, role=bot)."""
+
+def build_create_channel_event(
+    secret: str,
+    channel_id: str,
+    name: str,
+    visibility: str | None = ...,
+    channel_type: str | None = ...,
+    about: str | None = ...,
+    ttl: int | None = ...,
+) -> str:
+    """Build + sign a NIP-29 create-channel event (kind 9007)."""
+
+def build_huddle_started_event(
+    secret: str, parent_channel_id: str, ephemeral_channel_id: str
+) -> str:
+    """Build + sign a huddle-started advisory (kind 48100) for the parent channel."""
+
+def build_presence_event(secret: str, status: str = ...) -> str:
+    """Build + sign a presence event (kind 20001); status online/away/offline."""
+
+def build_auth_event(
+    secret: str, challenge: str, relay_url: str, auth_tag: str | None = ...
+) -> str:
+    """Build + sign a NIP-42 AUTH event (kind 22242); returns event JSON."""
+
+def compute_auth_tag(owner_secret: str, agent_pubkey_hex: str, conditions: str = ...) -> str:
+    """Compute a NIP-OA owner-attestation tag JSON attesting an agent pubkey."""
+
+def sign_nip98(secret: str, method: str, url: str, body: bytes | None = ...) -> str:
+    """Return an ``Authorization: Nostr <base64>`` header value (NIP-98)."""
+
+def verify_event(event_json: str) -> bool:
+    """Verify an event's id + Schnorr signature."""
+
+class HuddleEncoder:
+    """Stateful huddle audio encoder: s16le mono 48 kHz PCM in, v2 wire frames out."""
+
+    def __init__(self, bitrate: int = 32000, dtx: bool = True) -> None: ...
+    def encode(self, pcm: bytes) -> list[bytes]:
+        """Feed PCM; returns complete 20 ms wire frames (partials are buffered)."""
+
+    def flush(self) -> bytes | None:
+        """Zero-pad and emit the buffered partial frame, if any."""
+
+    def discard(self) -> None:
+        """Drop buffered PCM without emitting it (barge-in)."""
+
+class HuddleDecoder:
+    """Stateful huddle audio decoder for relay frames ([peer_index][header][opus])."""
+
+    def __init__(self) -> None: ...
+    def decode(self, frame: bytes) -> tuple[int, int, int, int, bool, bytes]:
+        """Return ``(peer_index, seq, ts_48k, level_dbov, is_dtx, pcm_s16le_48k)``."""
+
+    def remove_peer(self, peer_index: int) -> None:
+        """Forget a peer's decoder state (indexes are recycled by the relay)."""
+
+KIND_REACTION: int
+KIND_STREAM_MESSAGE: int
+KIND_PRESENCE_UPDATE: int
+KIND_AUTH: int
+KIND_HTTP_AUTH: int
+KIND_STREAM_MESSAGE_V2: int
+KIND_ADD_MEMBER: int
+KIND_CREATE_CHANNEL: int
+KIND_HUDDLE_STARTED: int
+KIND_HUDDLE_PARTICIPANT_JOINED: int
+KIND_HUDDLE_PARTICIPANT_LEFT: int
+KIND_HUDDLE_ENDED: int
+HUDDLE_PROTOCOL_VERSION: int
+HUDDLE_SAMPLE_RATE: int
+HUDDLE_FRAME_SAMPLES: int

buzzkit/client.py

@@ -0,0 +1,351 @@
+"""Async client for a Buzz relay: HTTP bridge + authenticated WebSocket.
+
+HTTP methods (:meth:`BuzzClient.post_event`, :meth:`send_message`,
+:meth:`query`, :meth:`claim_invite`, …) are one-shot and need no connection.
+WebSocket methods (:meth:`subscribe`, :meth:`publish`) require :meth:`connect`
+first — or use the client as an async context manager::
+
+    async with BuzzClient(relay_url, nsec) as bz:
+        async for event in bz.subscribe_channel(channel_id):
+            ...
+
+Reconnection is intentionally left to the caller (e.g. RoomKit's SourceProvider
+already owns reconnect/health); on a dropped socket, active subscriptions receive
+a final ``closed`` and their iterators stop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+import uuid
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+import websockets
+
+from . import _native
+
+logger = logging.getLogger("buzzkit.client")
+
+_AUTH_TIMEOUT = 20.0
+_OK_TIMEOUT = 20.0
+_MAX_FRAME = 1 << 20  # 1 MiB — matches the relay's max frame size
+
+
+def _to_http(relay_url: str) -> str:
+    u = relay_url.rstrip("/")
+    if u.startswith("wss://"):
+        return "https://" + u[len("wss://") :]
+    if u.startswith("ws://"):
+        return "http://" + u[len("ws://") :]
+    return u
+
+
+def _to_ws(relay_url: str) -> str:
+    u = relay_url.rstrip("/")
+    if u.startswith("https://"):
+        return "wss://" + u[len("https://") :]
+    if u.startswith("http://"):
+        return "ws://" + u[len("http://") :]
+    return u
+
+
+class BuzzClient:
+    """A Buzz relay client, keyed by a single Nostr secret (agent identity)."""
+
+    def __init__(self, relay_url: str, secret: str, *, auth_tag: str | None = None) -> None:
+        self.relay_url = relay_url
+        self._http = _to_http(relay_url)
+        self._ws_url = _to_ws(relay_url)
+        self._secret = secret
+        self._auth_tag = auth_tag  # NIP-OA owner attestation (AUTH + profile)
+        self.npub, self.pubkey_hex = _native.pubkey_from_secret(secret)
+        self._ws: Any = None
+        self._reader: asyncio.Task | None = None
+        self._authed = asyncio.Event()
+        self._auth_event_id: str | None = None
+        self._subs: dict[str, asyncio.Queue] = {}
+        self._pending_ok: dict[str, asyncio.Future] = {}
+
+    # ------------------------------------------------------------------ HTTP
+
+    def _nip98(self, method: str, url: str, body: bytes | None) -> str:
+        return _native.sign_nip98(self._secret, method, url, body)
+
+    async def post_event(self, event_json: str) -> dict:
+        """POST a signed event to the HTTP bridge (non-ephemeral kinds only)."""
+        url = f"{self._http}/events"
+        body = event_json.encode("utf-8")
+        headers = {
+            "Authorization": self._nip98("POST", url, body),
+            "Content-Type": "application/json",
+        }
+        async with httpx.AsyncClient(timeout=20.0) as c:
+            r = await c.post(url, content=body, headers=headers)
+            r.raise_for_status()
+            return r.json()
+
+    async def send_message(
+        self, channel_id: str, content: str, mentions: list[str] | None = None
+    ) -> dict:
+        """Build + post a channel chat message (kind 9)."""
+        ev = _native.build_message_event(self._secret, channel_id, content, mentions)
+        return await self.post_event(ev)
+
+    async def set_profile(
+        self,
+        display_name: str,
+        *,
+        about: str | None = None,
+        picture: str | None = None,
+        auth_tag: str | None = None,
+    ) -> dict:
+        """Publish this identity's profile (kind 0) so it shows a name in Buzz.
+
+        ``auth_tag`` defaults to the client's NIP-OA owner attestation, so a
+        client constructed with one automatically shows as "managed by
+        <owner>" in the Buzz desktop (which reads the tag from kind 0).
+        """
+        ev = _native.build_profile_event(
+            self._secret,
+            display_name=display_name,
+            name=display_name,
+            about=about,
+            picture=picture,
+            auth_tag=auth_tag if auth_tag is not None else self._auth_tag,
+        )
+        return await self.post_event(ev)
+
+    async def join_channel(self, channel_id: str) -> dict:
+        """Self-add as a bot member of a channel (NIP-29 kind 9000).
+
+        Published over the WebSocket — NIP-29 management events are not accepted
+        on the HTTP bridge — so :meth:`connect` must be called first. Required
+        for the identity's messages to reach other channel members and for it to
+        appear in mention autocomplete.
+        """
+        ev = _native.build_join_channel_event(self._secret, channel_id)
+        return await self.publish(ev)
+
+    async def start_huddle(
+        self, parent_channel_id: str, *, name: str | None = None, ttl: int = 3600
+    ) -> str:
+        """Start a huddle in a channel; returns the ephemeral huddle channel id.
+
+        Creates a private ephemeral channel (kind 9007, over the WebSocket —
+        :meth:`connect` first) and posts the kind-48100 announcement to the
+        parent channel. Join the audio with
+        ``HuddleClient(..., huddle_id, parent_channel_id=parent_channel_id)``.
+        """
+        huddle_id = str(uuid.uuid4())
+        create_ev = _native.build_create_channel_event(
+            self._secret,
+            huddle_id,
+            name or f"huddle-{huddle_id[:8]}",
+            visibility="private",
+            channel_type="stream",
+            ttl=ttl,
+        )
+        result = await self.publish(create_ev)
+        if not result["accepted"]:
+            raise RuntimeError(f"huddle channel rejected: {result['message']}")
+        started_ev = _native.build_huddle_started_event(
+            self._secret, parent_channel_id, huddle_id
+        )
+        result = await self.publish(started_ev)
+        if not result["accepted"]:
+            raise RuntimeError(f"huddle announcement rejected: {result['message']}")
+        return huddle_id
+
+    async def publish_presence(self, status: str = "online") -> dict:
+        """Announce presence (kind 20001, ephemeral) over the WebSocket."""
+        ev = _native.build_presence_event(self._secret, status)
+        return await self.publish(ev)
+
+    async def query(self, filters: list[dict]) -> list[dict]:
+        """Run a NIP-01 REQ over the HTTP bridge; returns a list of events."""
+        url = f"{self._http}/query"
+        body = json.dumps(filters).encode("utf-8")
+        headers = {
+            "Authorization": self._nip98("POST", url, body),
+            "Content-Type": "application/json",
+        }
+        async with httpx.AsyncClient(timeout=20.0) as c:
+            r = await c.post(url, content=body, headers=headers)
+            r.raise_for_status()
+            data = r.json()
+            return data if isinstance(data, list) else []
+
+    async def list_channels(self) -> list[dict]:
+        """List channel metadata (kind 39000) as ``{channel_id, name, event}``."""
+        out = []
+        for ev in await self.query([{"kinds": [39000], "limit": 500}]):
+            tags = {t[0]: t[1] for t in ev.get("tags", []) if len(t) >= 2}
+            out.append({"channel_id": tags.get("d"), "name": tags.get("name"), "event": ev})
+        return out
+
+    async def claim_invite(self, code_or_url: str) -> dict:
+        """Redeem a relay invite: accept the join-policy (if any), then claim.
+
+        Accepts a full ``.../invite/<code>`` URL or a bare code.
+        """
+        code = code_or_url.rsplit("/invite/", 1)[-1].strip().strip("/")
+        async with httpx.AsyncClient(timeout=20.0) as c:
+            policy = (await c.get(f"{self._http}/api/join-policy")).json().get("policy")
+            receipt = None
+            if policy:
+                rp = await c.post(
+                    f"{self._http}/api/invites/accept-policy",
+                    json={
+                        "code": code,
+                        "policy_version": policy["version"],
+                        "age_confirmed": True,
+                    },
+                )
+                rp.raise_for_status()
+                receipt = rp.json()["receipt"]
+            payload: dict = {"code": code}
+            if receipt:
+                payload["policy_receipt"] = receipt
+            url = f"{self._http}/api/invites/claim"
+            body = json.dumps(payload).encode("utf-8")
+            headers = {
+                "Authorization": self._nip98("POST", url, body),
+                "Content-Type": "application/json",
+            }
+            rc = await c.post(url, content=body, headers=headers)
+            rc.raise_for_status()
+            return rc.json()
+
+    # ------------------------------------------------------------- WebSocket
+
+    async def __aenter__(self) -> BuzzClient:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+    async def connect(self) -> None:
+        """Open the WebSocket and complete the NIP-42 auth handshake."""
+        self._authed.clear()
+        self._ws = await websockets.connect(self._ws_url, max_size=_MAX_FRAME)
+        self._reader = asyncio.create_task(self._read_loop())
+        await asyncio.wait_for(self._authed.wait(), timeout=_AUTH_TIMEOUT)
+
+    async def _read_loop(self) -> None:
+        try:
+            async for raw in self._ws:
+                try:
+                    msg = json.loads(raw)
+                except json.JSONDecodeError:
+                    continue
+                if not msg:
+                    continue
+                typ = msg[0]
+                if typ == "EVENT":
+                    q = self._subs.get(msg[1])
+                    if q is not None:
+                        await q.put(("event", msg[2]))
+                elif typ == "OK":
+                    self._on_ok(msg)
+                elif typ == "AUTH":
+                    await self._on_auth_challenge(msg[1])
+                elif typ == "EOSE":
+                    q = self._subs.get(msg[1])
+                    if q is not None:
+                        await q.put(("eose", None))
+                elif typ == "CLOSED":
+                    q = self._subs.get(msg[1])
+                    if q is not None:
+                        await q.put(("closed", msg[2] if len(msg) > 2 else ""))
+                elif typ == "NOTICE":
+                    logger.warning("relay NOTICE: %s", msg[1] if len(msg) > 1 else "")
+        except websockets.ConnectionClosed:
+            logger.info("buzz websocket closed")
+        finally:
+            for q in self._subs.values():
+                q.put_nowait(("closed", "connection lost"))
+
+    async def _on_auth_challenge(self, challenge: str) -> None:
+        auth_ev = json.loads(
+            _native.build_auth_event(self._secret, challenge, self._ws_url, self._auth_tag)
+        )
+        self._auth_event_id = auth_ev["id"]
+        await self._ws.send(json.dumps(["AUTH", auth_ev]))
+
+    def _on_ok(self, msg: list) -> None:
+        event_id = msg[1]
+        accepted = bool(msg[2]) if len(msg) > 2 else False
+        message = msg[3] if len(msg) > 3 else ""
+        if event_id == self._auth_event_id:
+            if accepted:
+                self._authed.set()
+            else:
+                logger.error("NIP-42 auth rejected: %s", message)
+            return
+        fut = self._pending_ok.pop(event_id, None)
+        if fut is not None and not fut.done():
+            fut.set_result((accepted, message))
+
+    async def publish(self, event_json: str) -> dict:
+        """Publish a signed event over the WebSocket and await the relay OK.
+
+        Use this for ephemeral kinds (20000–29999) which the HTTP bridge rejects.
+        """
+        if self._ws is None:
+            raise RuntimeError("call connect() before publish()")
+        ev = json.loads(event_json)
+        fut: asyncio.Future = asyncio.get_running_loop().create_future()
+        self._pending_ok[ev["id"]] = fut
+        await self._ws.send(json.dumps(["EVENT", ev]))
+        accepted, message = await asyncio.wait_for(fut, timeout=_OK_TIMEOUT)
+        return {"accepted": accepted, "event_id": ev["id"], "message": message}
+
+    async def subscribe(
+        self, filters: list[dict], *, sub_id: str = "sub", close_on_eose: bool = False
+    ) -> AsyncIterator[dict]:
+        """Subscribe with NIP-01 filters and async-iterate matching events."""
+        if self._ws is None:
+            raise RuntimeError("call connect() before subscribe()")
+        q: asyncio.Queue = asyncio.Queue()
+        self._subs[sub_id] = q
+        await self._ws.send(json.dumps(["REQ", sub_id, *filters]))
+        try:
+            while True:
+                kind, payload = await q.get()
+                if kind == "event":
+                    yield payload
+                elif kind == "eose":
+                    if close_on_eose:
+                        break
+                elif kind == "closed":
+                    break
+        finally:
+            self._subs.pop(sub_id, None)
+            # the socket may already be gone
+            with contextlib.suppress(Exception):
+                await self._ws.send(json.dumps(["CLOSE", sub_id]))
+
+    async def subscribe_channel(
+        self, channel_id: str, *, kinds: list[int] | None = None, **kw: Any
+    ) -> AsyncIterator[dict]:
+        """Subscribe to a channel's messages (default kind 9) via its h-tag."""
+        f = {"kinds": kinds or [_native.KIND_STREAM_MESSAGE], "#h": [channel_id]}
+        async for ev in self.subscribe([f], **kw):
+            yield ev
+
+    async def close(self) -> None:
+        """Cancel the reader task and close the WebSocket."""
+        if self._reader is not None:
+            self._reader.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._reader
+            self._reader = None
+        if self._ws is not None:
+            await self._ws.close()
+            self._ws = None