yapper.py 1.0.0__tar.gz → 1.2.0__tar.gz

{yapper_py-1.0.0/src/yapper.py.egg-info → yapper_py-1.2.0}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: yapper.py
-Version: 1.0.0
-Summary: An unofficial Python Library for Yapper
-Author-email: LeAndre C <leandre@lecanact.me>
+Version: 1.2.0
+Summary: A Python Library for Yapin'
+Author-email: "LeAndre C." <leandre@lecanact.me>
 License-Expression: GPL-3.0-only
 Project-URL: Repository, https://github.com/our-websites/yapper.py
 Project-URL: Issues, https://github.com/our-websites/yapper.py/issues
-Project-URL: Documentation, https://yapper.website/developers
+Project-URL: Documentation, https://yapin.gg/developers
+Keywords: yapper.py,yapin.py,discord.py,yapper,yapin
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10

{yapper_py-1.0.0 → yapper_py-1.2.0}/pyproject.toml

@@ -4,16 +4,23 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "yapper.py"
-version = "1.0.0"
+version = "1.2.0"
 authors = [
-  { name="LeAndre C", email="leandre@lecanact.me" },
+  { name="LeAndre C.", email="leandre@lecanact.me" },
 ]
-description = "An unofficial Python Library for Yapper"
+description = "A Python Library for Yapin'"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
     "python-dotenv>=1.2.4",
 ]
+keywords = [
+    "yapper.py",
+    "yapin.py",
+    "discord.py",
+    "yapper",
+    "yapin"
+]
 classifiers = [
     "Programming Language :: Python :: 3",
     "Operating System :: OS Independent",
@@ -24,7 +31,7 @@ license-files = ["LICEN[CS]E*"]
 [project.urls]
 Repository = "https://github.com/our-websites/yapper.py"
 Issues = "https://github.com/our-websites/yapper.py/issues"
-Documentation = "https://yapper.website/developers"
+Documentation = "https://yapin.gg/developers"
 
 [tool.setuptools.packages.find]
 where = ["src"]

yapper_py-1.2.0/src/yapper/__init__.py

@@ -0,0 +1,16 @@
+from .main import (
+    Bot,
+    VoiceCall,
+    Cog,
+    command,
+    listener,
+    button,
+    YapperError,
+    row,
+    btn,
+    link_button
+)
+
+__all__ = ["Bot", "VoiceCall", "Cog", "command", "listener", "button", "YapperError", "row", "btn", "link_button"]
+
+__version__ = "1.2"

{yapper_py-1.0.0 → yapper_py-1.2.0}/src/yapper/main.py

@@ -1,4 +1,4 @@
-"""Yapper bot library for Python. Python 3.10+, with python-dotenv as its only dependency.
+"""Yapin’ bot library for Python. One file, standard library only, Python 3.9+.
 
     import yapper
 
@@ -19,10 +19,12 @@
     bot.load_extensions("cogs")            # optional: every cogs/*.py (see Cog below)
     bot.run()
 
-Install it with `pip install yapper.py` (this also installs python-dotenv, which loads a .env file for you)
-and run your bot with `python bot.py`. Nothing to host: the bot fetches its own events from Yapper
-(long polling). Docs: https://www.yapper.website/developers
+Save this file next to your bot and run it with `python bot.py`. Nothing to install, nothing to host:
+the bot keeps one WebSocket open to Yapin’ (the gateway) and gets its events pushed; when that is off or down
+it fetches them itself (long polling). Docs: https://www.yapin.gg/developers
 """
+import base64
+import hashlib
 import importlib
 import importlib.util
 import inspect
@@ -30,6 +32,10 @@ import json
 import os
 import random
 import re
+import select
+import socket
+import ssl
+import struct
 import sys
 import time
 import traceback
@@ -40,7 +46,13 @@ from dotenv import load_dotenv
 
 load_dotenv()
 
-BASE = "https://www.yapper.website/api/bot/v1"
+__all__ = ["Bot", "VoiceCall", "Cog", "command", "listener", "button", "YapperError", "row", "btn", "link_button"]
+__version__ = "1.2"
+
+BASE = "https://bots.yapper.website/api/bot/v1"
+# The website's address for the same API: used for 10 minutes when BASE can't be reached.
+FALLBACK_BASE = "https://www.yapin.gg/api/bot/v1"
+GATEWAY = "wss://rt.yapper.website/bot"
 COMMAND_LIMIT = 100
 EVENTS = ("message", "command", "member_join", "member_leave", "reaction_add", "reaction_remove",
           "voice_join", "voice_leave", "interaction", "test", "ready", "error")
@@ -94,20 +106,20 @@ class Interaction(Data):
     """A button click: i.custom_id, i.user_id, i.username, and i.reply / i.ephemeral / i.update / i.ack.
     Answer within 3 seconds or the person sees "This interaction failed"."""
 
-    def _answer(self, kind, content=None, embeds=None, components=None):
-        return self._bot.respond(self, kind, content=content, embeds=embeds, components=components)
+    def _answer(self, kind, content=None, embeds=None, components=None, layout=None):
+        return self._bot.respond(self, kind, content=content, embeds=embeds, components=components, layout=layout)
 
-    def reply(self, content="", embeds=None, components=None):
-        """A new message in the channel."""
-        return self._answer("reply", content, embeds, components)
+    def reply(self, content="", embeds=None, components=None, layout=None):
+        """A new message in the channel. layout=[...] sends a Components V2 message instead."""
+        return self._answer("reply", None if layout is not None else content, embeds, components, layout)
 
     def ephemeral(self, content="", embeds=None):
         """A message only the person who clicked sees."""
         return self._answer("ephemeral", content, embeds)
 
-    def update(self, content=None, embeds=None, components=None):
-        """Change the message the button is on (left out = kept)."""
-        return self._answer("update", content, embeds, components)
+    def update(self, content=None, embeds=None, components=None, layout=None):
+        """Change the message the button is on (left out = kept). On a Components V2 message: update(layout=[...])."""
+        return self._answer("update", content, embeds, components, layout)
 
     def ack(self):
         """Just say "got it", so no error shows."""
@@ -136,6 +148,62 @@ def link_button(label, url):
     return {"type": "button", "style": "link", "label": label, "url": url}
 
 
+# ---- Components V2 (bot.send_layout): layout components, standard JSON shape and type numbers ----
+
+IS_COMPONENTS_V2 = 1 << 15
+_COLORS = {"red": 0xED4245, "green": 0x57F287, "blue": 0x5865F2, "yellow": 0xFEE75C, "purple": 0x9B59B6,
+           "orange": 0xE67E22, "grey": 0x95A5A6, "gray": 0x95A5A6}
+
+
+def _clean(d):
+    return {k: v for k, v in d.items() if v is not None and v is not False}
+
+
+def text(content):
+    """Markdown text (type 10). Mentions, links and emoji work like in messages; no HTML."""
+    return {"type": 10, "content": str(content)}
+
+
+def thumbnail(url, description=None, spoiler=False):
+    """A small picture (type 11), only as a section's accessory."""
+    return _clean({"type": 11, "media": {"url": url}, "description": description, "spoiler": spoiler})
+
+
+def section(*texts, accessory):
+    """1 to 3 lines of text with a button or a thumbnail beside them (type 9): section("Ready?", accessory=btn("Go", "go"))."""
+    return {"type": 9, "components": [t if isinstance(t, dict) else text(t) for t in texts], "accessory": accessory}
+
+
+def media(url, description=None, spoiler=False):
+    """One picture or video for gallery()."""
+    return _clean({"media": {"url": url}, "description": description, "spoiler": spoiler})
+
+
+def gallery(*items):
+    """1 to 10 pictures or videos in a grid (type 12): gallery("https://…", media("https://…", spoiler=True))."""
+    return {"type": 12, "items": [i if isinstance(i, dict) else media(i) for i in items]}
+
+
+def separator(divider=True, spacing="small"):
+    """A line (or just space with divider=False), spacing "small" or "large" (type 14)."""
+    return {"type": 14, "divider": bool(divider), "spacing": 2 if spacing in ("large", 2) else 1}
+
+
+def file_display(url, spoiler=False):
+    """A file to download (type 13): an https link to a Yapin’ upload or an allowed host."""
+    return _clean({"type": 13, "file": {"url": url}, "spoiler": spoiler})
+
+
+def container(*components, accent=None, spoiler=False):
+    """A card holding other components (type 17). accent: 0x5865F2, "#5865f2" or a name like "blue"."""
+    c = {"type": 17, "components": [x if isinstance(x, dict) else text(x) for x in components]}
+    if accent is not None:
+        c["accent_color"] = accent if isinstance(accent, int) else _COLORS.get(str(accent).lower()) or int(str(accent).lstrip("#"), 16)
+    if spoiler:
+        c["spoiler"] = True
+    return c
+
+
 # ---- decorators for cogs (on a Cog's methods) ----
 
 def command(name=None, description=""):
@@ -210,18 +278,172 @@ class _Owner:
         self.cogs = []        # for a file: the cogs its setup added
 
 
+def _backoff(n):
+    """Seconds to wait before try number n (1, 2, ...): 1, 2, 4 ... up to 30, with some jitter so many bots don't sync up."""
+    return min(30, 2 ** (n - 1)) * (0.75 + random.random() / 2)
+
+
+class _GatewayClosed(Exception):
+    """The gateway closed the socket. `.code` is the close code (0 when the connection just dropped)."""
+
+    def __init__(self, code=0, reason=""):
+        super().__init__(reason or f"gateway closed ({code})")
+        self.code = code
+        self.reason = reason
+
+
+def _mask(data, key):
+    n = len(data)
+    return (int.from_bytes(data, "big") ^ int.from_bytes((key * (n // 4 + 1))[:n], "big")).to_bytes(n, "big")
+
+
+class _WebSocket:
+    """Just enough of a WebSocket client (RFC 6455) for the gateway: text messages, ping/pong, close codes, TLS.
+    Standard library only, so the SDK still needs nothing installed."""
+
+    def __init__(self, url, timeout=15):
+        u = urllib.parse.urlsplit(url)
+        if u.scheme not in ("ws", "wss") or not u.hostname:
+            raise ValueError(f"Not a WebSocket URL: {url}")
+        tls = u.scheme == "wss"
+        port = u.port or (443 if tls else 80)
+        path = (u.path or "/") + (f"?{u.query}" if u.query else "")
+        self._buf = b""
+        self._frag = None   # [opcode, bytearray] of a message still arriving in pieces
+        self.sock = socket.create_connection((u.hostname, port), timeout=timeout)
+        try:
+            self.sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+            if tls:
+                self.sock = ssl.create_default_context().wrap_socket(self.sock, server_hostname=u.hostname)
+            key = base64.b64encode(os.urandom(16)).decode()
+            host = u.hostname if port == (443 if tls else 80) else f"{u.hostname}:{port}"
+            self.sock.sendall((f"GET {path} HTTP/1.1\r\nHost: {host}\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n"
+                               f"Sec-WebSocket-Key: {key}\r\nSec-WebSocket-Version: 13\r\n"
+                               f"User-Agent: yapper-py/{__version__}\r\n\r\n").encode())
+            head = self._read_until(b"\r\n\r\n")
+            status, _, rest = head.partition(b"\r\n")
+            if b" 101 " not in status:
+                raise OSError(f"gateway handshake failed: {status.decode(errors='replace')[:80]}")
+            headers = {}
+            for line in rest.split(b"\r\n"):
+                k, _, v = line.decode(errors="replace").partition(":")
+                headers[k.strip().lower()] = v.strip()
+            want = base64.b64encode(hashlib.sha1((key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11").encode()).digest()).decode()
+            if headers.get("sec-websocket-accept") != want:
+                raise OSError("gateway handshake failed: bad Sec-WebSocket-Accept")
+        except BaseException:
+            self.sock.close()
+            raise
+
+    def _read_until(self, mark):
+        while mark not in self._buf:
+            chunk = self.sock.recv(4096)
+            if not chunk:
+                raise OSError("gateway closed during the handshake")
+            self._buf += chunk
+            if len(self._buf) > 65536:
+                raise OSError("gateway handshake answer too long")
+        head, self._buf = self._buf.split(mark, 1)
+        return head
+
+    def _read(self, n):
+        while len(self._buf) < n:
+            chunk = self.sock.recv(max(4096, n - len(self._buf)))
+            if not chunk:
+                raise _GatewayClosed(0, "connection lost")
+            self._buf += chunk
+        out, self._buf = self._buf[:n], self._buf[n:]
+        return out
+
+    def _frame(self, opcode, payload=b""):
+        n = len(payload)
+        if n < 126:
+            head = bytes([0x80 | opcode, 0x80 | n])
+        elif n < 65536:
+            head = bytes([0x80 | opcode, 0x80 | 126]) + struct.pack("!H", n)
+        else:
+            head = bytes([0x80 | opcode, 0x80 | 127]) + struct.pack("!Q", n)
+        key = os.urandom(4)
+        self.sock.sendall(head + key + _mask(payload, key))
+
+    def send(self, obj):
+        self._frame(1, json.dumps(obj).encode())
+
+    def readable(self, wait):
+        """True when something can be read within `wait` seconds (bytes TLS already took off the wire count too)."""
+        if self._buf or getattr(self.sock, "pending", lambda: 0)():
+            return True
+        r, _, _ = select.select([self.sock], [], [], max(0.0, wait))
+        return bool(r)
+
+    def recv(self):
+        """The next text message as a string (None for a binary one). Answers pings itself; raises _GatewayClosed
+        when the other side closes."""
+        while True:
+            b1, b2 = self._read(2)
+            fin, opcode, n = b1 & 0x80, b1 & 0x0F, b2 & 0x7F
+            if n == 126:
+                n = struct.unpack("!H", self._read(2))[0]
+            elif n == 127:
+                n = struct.unpack("!Q", self._read(8))[0]
+            if n > 16 * 1024 * 1024:
+                raise OSError("gateway frame too big")
+            key = self._read(4) if b2 & 0x80 else None
+            data = self._read(n)
+            if key:
+                data = _mask(data, key)
+            if opcode == 8:
+                code = struct.unpack("!H", data[:2])[0] if len(data) >= 2 else 0
+                try:
+                    self._frame(8, data[:2])
+                except OSError:
+                    pass
+                raise _GatewayClosed(code, data[2:].decode("utf-8", "replace"))
+            if opcode == 9:
+                self._frame(10, data)
+            elif opcode in (1, 2):
+                if fin:
+                    return data.decode("utf-8", "replace") if opcode == 1 else None
+                self._frag = [opcode, bytearray(data)]
+            elif opcode == 0 and self._frag:
+                self._frag[1] += data
+                if fin:
+                    op, whole = self._frag
+                    self._frag = None
+                    return bytes(whole).decode("utf-8", "replace") if op == 1 else None
+
+    def close(self, code=1000, reason=""):
+        try:
+            self._frame(8, struct.pack("!H", code) + reason.encode()[:120])
+        except OSError:
+            pass
+        try:
+            self.sock.close()
+        except OSError:
+            pass
+
+
 class Bot:
-    def __init__(self, token=None, base=BASE, prefixes=("/", "!"), log=True, ignore_bots=True):
+    def __init__(self, token=None, base=None, prefixes=("/", "!"), log=True, ignore_bots=True, gateway=GATEWAY):
         """`token` defaults to the YAPPER_BOT_TOKEN environment variable (bot hosting sets it for you).
-        `ignore_bots` (default True): skip messages from other bots and webhooks, so bots can't reply to each other forever."""
+        `ignore_bots` (default True): skip messages from other bots and webhooks, so bots can't reply to each other forever.
+        `gateway` (default on): where events come from over a WebSocket; used when it's on for your bot, otherwise
+        the bot long-polls. Pass None (or False) to always poll."""
         token = (token or os.environ.get("YAPPER_BOT_TOKEN") or "").strip()
         if not token.startswith("yb_"):
             raise SystemExit("Pass your bot token (starts with yb_) or set YAPPER_BOT_TOKEN. Get one in Settings -> Developer.")
         self.token = token
-        self.base = base.rstrip("/")
+        # YAPPER_API_URL: set by bot hosting (usable anywhere) to point at another API host.
+        chosen = base or os.environ.get("YAPPER_API_URL")
+        self.base = (chosen or BASE).rstrip("/")
+        # Hosted bots get our host through YAPPER_API_URL: they keep the fallback too; any other chosen base doesn't.
+        self._fallback = None if chosen and self.base != BASE else FALLBACK_BASE
+        self._fallback_until = 0
         self.prefixes = tuple(prefixes)
         self.log = log
         self.ignore_bots = ignore_bots
+        self.gateway = gateway or None
+        self._ws = None
         self.me = None
         self.last = 0
         self.running = False
@@ -472,16 +694,25 @@ class Bot:
     # ---- HTTP ----
 
     def api(self, method, path, body=None, timeout=40, retries=3):
-        """Raw API call: bot.api("GET", "/servers"). A 429 with Retry-After, or Yapper's own 503 "busy",
+        """Raw API call: bot.api("GET", "/servers"). A 429 with Retry-After, or Yapin’s own 503 "busy",
         is waited out and retried (nothing was done, so that's safe). Other errors raise YapperError."""
         data = None if body is None else json.dumps(body).encode()
-        req = urllib.request.Request(self.base + path, method=method, data=data, headers={
-            "Authorization": f"Bot {self.token}", "Content-Type": "application/json", "User-Agent": "yapper-py/1"})
+        on_fallback = bool(self._fallback) and time.time() < self._fallback_until
+        base = self._fallback if on_fallback else self.base
+        req = urllib.request.Request(base + path, method=method, data=data, headers={
+            "Authorization": f"Bot {self.token}", "Content-Type": "application/json", "User-Agent": f"yapper-py/{__version__}"})
         try:
             with urllib.request.urlopen(req, timeout=timeout) as r:
                 raw = r.read()
-                return json.loads(raw) if raw else {}
+                try:
+                    return json.loads(raw) if raw else {}
+                except ValueError:
+                    raise YapperError(f"{method} {path}: the server sent something that isn't JSON (is the API address right?)", r.status) from None
         except urllib.error.HTTPError as e:
+            if e.code in (502, 504) and self._fallback and not on_fallback:
+                self._use_fallback(f"answered {e.code}")
+                if method == "GET" and retries > 0:
+                    return self.api(method, path, body, timeout, retries - 1)
             try:
                 err = json.loads(e.read() or b"{}")
             except Exception:
@@ -497,10 +728,24 @@ class Bot:
                     wait = 0
             if 0 < wait <= 60 and retries > 0:
                 if self.log:
-                    print(f"[yapper] {'Yapper busy' if busy else 'rate limited'}, retrying {method} {path} in {wait:g}s")
+                    print(f"[yapper] {'busy' if busy else 'rate limited'}, retrying {method} {path} in {wait:g}s")
                 time.sleep(wait * (1 + random.random() * 0.5))
                 return self.api(method, path, body, timeout, retries - 1)
             raise YapperError(err.get("error") or f"{method} {path} failed ({e.code})", e.code, wait or None) from None
+        except urllib.error.URLError:
+            # Our API host unreachable: the website's address for 10 minutes. A GET is asked again there at once;
+            # anything else isn't (it may have gone through), the next call goes there.
+            if not self._fallback or on_fallback:
+                raise
+            self._use_fallback("unreachable")
+            if method == "GET" and retries > 0:
+                return self.api(method, path, body, timeout, retries - 1)
+            raise
+
+    def _use_fallback(self, why):
+        self._fallback_until = time.time() + 600
+        if self.log:
+            print(f"[yapper] {self.base} {why}, using {self._fallback} for 10 minutes")
 
     # ---- messages and more ----
 
@@ -515,6 +760,19 @@ class Bot:
             body["components"] = components if isinstance(components, list) else [components]
         return Data(self.api("POST", f"/channels/{channel_id}/messages", body).get("message") or {})
 
+    def send_layout(self, channel_id, components, reply_to=None):
+        """Post a Components V2 message: the layout is the whole message (no content or embeds).
+        bot.send_layout(ch, [container(text("# Hi"), section("Ready?", accessory=btn("Go", "go")), accent="blue")])"""
+        body = {"flags": IS_COMPONENTS_V2, "components": components if isinstance(components, list) else [components]}
+        if reply_to:
+            body["reply_to"] = reply_to
+        return Data(self.api("POST", f"/channels/{channel_id}/messages", body).get("message") or {})
+
+    def edit_layout(self, channel_id, message_id, components):
+        """Swap the layout of one of the bot's Components V2 messages."""
+        body = {"flags": IS_COMPONENTS_V2, "components": components if isinstance(components, list) else [components]}
+        return Data(self.api("PATCH", f"/channels/{channel_id}/messages/{message_id}", body).get("message") or {})
+
     def edit(self, channel_id, message_id, content=None, embeds=None, components=None):
         body = {}
         if content is not None:
@@ -531,8 +789,8 @@ class Bot:
     def react(self, channel_id, message_id, emoji):
         return self.api("PUT", f"/channels/{channel_id}/messages/{message_id}/reactions/{urllib.parse.quote(emoji)}")
 
-    def respond(self, interaction, kind, content=None, embeds=None, components=None):
-        """Answer a button click: kind is reply, ephemeral, update or ack."""
+    def respond(self, interaction, kind, content=None, embeds=None, components=None, layout=None):
+        """Answer a button click: kind is reply, ephemeral, update or ack. layout=[...]: a Components V2 layout."""
         body = {"type": kind}
         if content is not None:
             body["content"] = str(content)
@@ -540,6 +798,9 @@ class Bot:
             body["embeds"] = embeds
         if components is not None:
             body["components"] = components
+        if layout is not None:
+            body["flags"] = IS_COMPONENTS_V2
+            body["components"] = layout if isinstance(layout, list) else [layout]
         return self.api("POST", f"/interactions/{interaction['id']}/{interaction['token']}/callback", body)
 
     def servers(self):
@@ -596,6 +857,53 @@ class Bot:
         """Time someone out for `minutes` (0 clears it)."""
         return self.api("POST", f"/servers/{server_id}/timeouts", {"user_id": user_id, "minutes": minutes, "reason": reason})
 
+    # ---- voice (Move Members for moves; 30 moves and 60 lookups a minute per bot) ----
+    def voice(self, server_id):
+        """Who is in voice: [{channel_id, user_ids}] for every voice channel the bot can see (empty ones too)."""
+        return self.api("GET", f"/servers/{server_id}/voice")["voice"]
+
+    def move_member(self, server_id, user_id, channel_id):
+        return self.api("POST", f"/servers/{server_id}/voice/move", {"user_id": user_id, "channel_id": channel_id})
+
+    def disconnect_member(self, server_id, user_id):
+        return self.api("POST", f"/servers/{server_id}/voice/disconnect", {"user_id": user_id})
+
+    # ---- the bot in voice: music bots (10 joins and leaves a minute; one voice channel per server) ----
+    def join_voice(self, server_id, channel_id):
+        """A ticket for a voice channel: {url, token, e2ee, voice_muted, channel_id, server_id}. Connect with any
+        LiveKit SDK within a minute. The bot sends one audio track (as a mic) and hears nobody. Joining another
+        channel of the same server drops it from the first. Most bots want connect_voice, which does all of it."""
+        return self.api("POST", f"/servers/{server_id}/voice/join", {"channel_id": channel_id})
+
+    def leave_voice(self, server_id):
+        """Take the bot out of voice in that server."""
+        return self.api("POST", f"/servers/{server_id}/voice/leave")
+
+    async def connect_voice(self, server_id, channel_id, sample_rate=48000, channels=2):
+        """Join a voice channel and get an audio source to play into. Needs `pip install livekit cryptography`
+        (only for this; the rest of this file stays standard library). Returns a VoiceCall: .room, .source (an
+        rtc.AudioSource: await source.capture_frame(rtc.AudioFrame(...))) and `await call.leave()`.
+        Calls on Yapin’ are end-to-end encrypted: this hands the bot's media key to everyone in the call the way the
+        app does (sealed to each person, the server never sees it) and encrypts the audio with it."""
+        import asyncio
+        from livekit import rtc  # noqa: deferred so the library works without it
+        t = await asyncio.to_thread(self.join_voice, server_id, channel_id)
+        media_key = os.urandom(32) if t.get("e2ee") else None
+        room = rtc.Room()
+        opts = rtc.RoomOptions(auto_subscribe=False)
+        if media_key:
+            # Shared key mode encrypts our frames with media_key; HKDF (1) is how the app's browsers turn it into the frame key.
+            # `e2ee`, not `encryption` (which livekit marks as the new name): `encryption` also encrypts data messages,
+            # so the key handoff went out sealed under the key it carries and the app never got it (silent bot).
+            opts.e2ee = rtc.E2EEOptions(key_provider_options=rtc.KeyProviderOptions(
+                shared_key=media_key, ratchet_window_size=0, key_ring_size=16, key_derivation_function=1))
+        await room.connect(t["url"], t["token"], opts)
+        keys = await _hand_out_voice_key(room, media_key) if media_key else None
+        source = rtc.AudioSource(sample_rate, channels)
+        track = rtc.LocalAudioTrack.create_audio_track("audio", source)
+        await room.local_participant.publish_track(track, rtc.TrackPublishOptions(source=rtc.TrackSource.SOURCE_MICROPHONE, dtx=False))
+        return VoiceCall(room, source, track, bool(media_key), keys)
+
     def dm(self, user_id):
         """Open a DM with someone. Returns the channel id."""
         return self.api("POST", f"/users/{user_id}/dm")["channel_id"]
@@ -647,10 +955,20 @@ class Bot:
                 return
             msg = Message.of(data, self)
             name, args = data.get("command"), data.get("args")
-            if not name:
-                m = re.match(r"^(\S)([a-z0-9_-]{1,32})(?:\s+([\s\S]*))?$", data.get("content") or "", re.I)
-                if m and m.group(1) in self.prefixes and m.group(2).lower() in self.commands:
-                    name, args = m.group(2).lower(), (m.group(3) or "").strip()
+            # "/fish @OtherBot": a command picked for another bot (command_for) isn't ours to answer, even if we have /fish.
+            cf = data.get("command_for")
+            for_other = isinstance(cf, list) and (self.me or {}).get("id") not in cf
+            if not name and not for_other:
+                # A prefix can be longer than one character ("yap!"); the longest one that fits goes first,
+                # so "!!" wins over "!".
+                content = data.get("content") or ""
+                for p in sorted(self.prefixes, key=len, reverse=True):
+                    if not p or not content.startswith(p):
+                        continue
+                    m = re.match(r"^([a-z0-9_-]{1,32})(?:\s+([\s\S]*))?$", content[len(p):], re.I)
+                    if m and m.group(1).lower() in self.commands:
+                        name, args = m.group(1).lower(), (m.group(2) or "").strip()
+                        break
             c = self.commands.get(name) if name else None
             if c:
                 msg.command, msg.args = name, args or ""
@@ -679,10 +997,13 @@ class Bot:
                         self._fail(e, b["owner"], "button " + b["prefix"])
             self._emit("interaction", i)
         else:
+            if kind == "test" and not self._listeners.get("test") and self.log:
+                # "Send test event" in the developer settings: with no listener it used to vanish silently.
+                print(f"[yapper] test event received{' (' + data['message'] + ')' if isinstance(data.get('message'), str) else ''}: the bot is connected and getting events")
             self._emit(kind, Data(data, type=kind))
 
     def sync_commands(self):
-        """Send the command list to Yapper (run() does it, and again after cogs change)."""
+        """Send the command list to Yapin’ (run() does it, and again after cogs change)."""
         self._dirty = False
         cmds = [{"name": n, "description": c["description"]} for n, c in self.commands.items()]
         self.api("PUT", "/commands", {"commands": cmds})
@@ -694,6 +1015,11 @@ class Bot:
             self._run()
         except KeyboardInterrupt:
             print("[yapper] stopped")
+        except YapperError as e:
+            hint = {400: "the request was rejected", 401: "the token was rejected: make a new one in Settings -> Developer",
+                    403: "this bot isn't allowed to do that"}.get(e.status, "")
+            print(f"[yapper] could not start ({e.status}): {e}" + (f"\n[yapper] {hint}" if hint else ""))
+            raise SystemExit(1) from None
         finally:
             self.running = False
             self._registered = False
@@ -725,14 +1051,33 @@ class Bot:
             print(f"[yapper] {self.me.username} is online" + (f" with {len(cmds)} command{'' if len(cmds) == 1 else 's'}" if cmds else ""))
         self._emit("ready", self.me)
         fails = 0
+        gw_fails = 0
+        gw_retry_at = 0.0
         while self.running:
-            if self._dirty:   # a cog was loaded or unloaded: send the new list once
-                try:
-                    n = len(self.sync_commands())
-                    if self.log:
-                        print(f"[yapper] commands updated ({n})")
-                except Exception as e:
-                    self._fail(e)
+            self._sync_if_dirty()
+            # The gateway first; when it's off for this bot or keeps failing, the long poll below for a while.
+            if self.gateway and time.time() >= gw_retry_at:
+                r = self._gateway_session()
+                if not self.running:
+                    break
+                if r == "bad_token":
+                    raise SystemExit("Token rejected: make a new one in Settings -> Developer")
+                if r == "disabled":
+                    gw_retry_at = time.time() + 10 * 60
+                elif r == "ok":
+                    gw_fails = 0
+                    time.sleep(_backoff(1))
+                    continue
+                else:
+                    gw_fails += 1
+                    if gw_fails >= 3:
+                        if self.log:
+                            print("[yapper] gateway unavailable, long polling for 5 minutes")
+                        gw_fails = 0
+                        gw_retry_at = time.time() + 5 * 60
+                    else:
+                        time.sleep(_backoff(gw_fails))
+                        continue
             try:
                 out = self.api("GET", f"/events?after={self.last}&wait=25", retries=0)
                 fails = 0
@@ -752,9 +1097,94 @@ class Bot:
 
     start = run
 
+    def _sync_if_dirty(self):
+        if not self._dirty:   # a cog was loaded or unloaded: send the new list once
+            return
+        try:
+            n = len(self.sync_commands())
+            if self.log:
+                print(f"[yapper] commands updated ({n})")
+        except Exception as e:
+            self._fail(e)
+
+    def _gateway_session(self):
+        """One gateway connection (docs: /developers#gateway). Picks up after self.last, so nothing is missed between
+        a long poll and the socket or across reconnects. Returns when the socket closes: "ok" (was up a while, connect
+        again), "disabled" (not on for this bot: long poll), "bad_token" or "failed"."""
+        try:
+            ws = _WebSocket(self.gateway, timeout=15)
+        except (OSError, ValueError, _GatewayClosed):
+            return "failed"
+        self._ws = ws
+        ready_at = 0.0
+        interval = 30.0
+        next_beat = 0.0
+        acked = True
+        result = "failed"
+        try:
+            while self.running:
+                if ready_at and time.time() >= next_beat:
+                    if not acked:   # no answer to the last heartbeat: the connection is dead, start over
+                        result = "ok"
+                        break
+                    acked = False
+                    ws.send({"op": "heartbeat"})
+                    next_beat = time.time() + interval
+                    continue
+                # A socket that never gets to ready doesn't hold the bot up: 15 s, then the next try (or the long poll).
+                if not ws.readable(next_beat - time.time() if ready_at else 15.0):
+                    if not ready_at:
+                        break
+                    continue
+                raw = ws.recv()
+                if raw is None:
+                    continue
+                try:
+                    msg = json.loads(raw)
+                except ValueError:
+                    continue
+                if not isinstance(msg, dict):
+                    continue
+                op = msg.get("op")
+                if op == "hello":
+                    ws.send({"op": "resume", "token": self.token, "seq": self.last})
+                elif op == "ready":
+                    ready_at = time.time()
+                    interval = max(5.0, (msg.get("heartbeat_interval") or 30000) / 1000)
+                    next_beat = ready_at + interval
+                    if self.log:
+                        print("[yapper] connected to the gateway")
+                elif op == "heartbeat_ack":
+                    acked = True
+                elif op == "event" and isinstance(msg.get("d"), dict):
+                    ev = msg["d"]
+                    # Each event once, in order: anything at or below the cursor was already handled.
+                    if isinstance(ev.get("id"), int) and ev["id"] > self.last:
+                        self.last = ev["id"]
+                        try:
+                            self.handle(ev)
+                        except Exception as e:
+                            self._fail(e)
+                    self._sync_if_dirty()
+        except _GatewayClosed as c:
+            up = ready_at and time.time() - ready_at > 10
+            result = "bad_token" if c.code == 4004 else "disabled" if c.code == 4003 else "ok" if up else "failed"
+        except OSError:
+            result = "ok" if ready_at and time.time() - ready_at > 10 else "failed"
+        finally:
+            ws.close(1000 if not self.running else 4000)
+            self._ws = None
+        return result
+
     def stop(self):
-        """Stop after the current poll."""
+        """Stop after the current poll (or close the gateway socket)."""
         self.running = False
+        ws = self._ws
+        if ws is not None:
+            try:
+                ws.close()
+            except Exception:
+                pass
 
 
 def _module_name(name):
@@ -772,3 +1202,79 @@ def _module_name(name):
         mod = os.path.splitext(os.path.basename(path))[0]
         return (f"{parent}.{mod}" if parent.isidentifier() else mod), path
     return s, None
+
+
+class VoiceCall:
+    """A bot in a voice channel (Bot.connect_voice): .room, .source, .track, .e2ee, and `await call.leave()`."""
+
+    def __init__(self, room, source, track, e2ee, keys):
+        self.room, self.source, self.track, self.e2ee, self._keys = room, source, track, e2ee, keys
+
+    async def leave(self):
+        if self._keys:
+            self._keys()
+        await self.room.disconnect()
+
+
+async def _hand_out_voice_key(room, media_key):
+    """Encrypted calls: the bot's half of the app's key handoff. Our P-256 public key goes in the participant
+    attribute `e2ee`; everyone who has one gets our media key over the data channel (topic yapper-e2ee), sealed with
+    AES-GCM under the ECDH secret the two of us share and bound to "<from>|<to>|<index>". The bot hears nobody, so it
+    never needs anyone's key back, only to answer when someone sends theirs. Returns a function that stops it."""
+    import asyncio
+    import base64
+    from cryptography.hazmat.primitives.asymmetric import ec
+    from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+    from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+
+    me = room.local_participant.identity
+    priv = ec.generate_private_key(ec.SECP256R1())
+    my_pub = base64.b64encode(priv.public_key().public_bytes(Encoding.X962, PublicFormat.UncompressedPoint)).decode()
+    sent, shared, state = {}, {}, {"stopped": False}
+
+    async def send_to(p, pub=None):
+        their = (p.attributes or {}).get("e2ee") or pub
+        if state["stopped"] or not their or p.identity == me or sent.get(p.identity) == their:
+            return
+        sent[p.identity] = their
+        try:
+            if their not in shared:
+                peer = ec.EllipticCurvePublicKey.from_encoded_point(ec.SECP256R1(), base64.b64decode(their))
+                shared[their] = AESGCM(priv.exchange(ec.ECDH(), peer))
+            iv = os.urandom(12)
+            ct = shared[their].encrypt(iv, media_key, f"{me}|{p.identity}|0".encode())
+            msg = json.dumps({"i": 0, "iv": base64.b64encode(iv).decode(), "ct": base64.b64encode(ct).decode(), "k": my_pub})
+            await room.local_participant.publish_data(msg.encode(), reliable=True, topic="yapper-e2ee", destination_identities=[p.identity])
+        except Exception:
+            sent.pop(p.identity, None)  # muted by a moderator (no data permission) or a bad key: try again on the next change
+
+    def on_peer(p):
+        asyncio.ensure_future(send_to(p))
+
+    def on_attrs(_changed, p):
+        asyncio.ensure_future(send_to(p))
+
+    def on_data(packet):
+        if packet.topic != "yapper-e2ee" or packet.participant is None:
+            return
+        try:
+            k = json.loads(packet.data.decode()).get("k")
+        except Exception:
+            return
+        if isinstance(k, str):
+            sent.pop(packet.participant.identity, None)
+            asyncio.ensure_future(send_to(packet.participant, k))
+
+    room.on("participant_connected", on_peer)
+    room.on("participant_attributes_changed", on_attrs)
+    room.on("data_received", on_data)
+    await room.local_participant.set_attributes({"e2ee": my_pub})
+    for p in list(room.remote_participants.values()):
+        await send_to(p)
+
+    def stop():
+        state["stopped"] = True
+        room.off("participant_connected", on_peer)
+        room.off("participant_attributes_changed", on_attrs)
+        room.off("data_received", on_data)
+    return stop

{yapper_py-1.0.0 → yapper_py-1.2.0/src/yapper.py.egg-info}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: yapper.py
-Version: 1.0.0
-Summary: An unofficial Python Library for Yapper
-Author-email: LeAndre C <leandre@lecanact.me>
+Version: 1.2.0
+Summary: A Python Library for Yapin'
+Author-email: "LeAndre C." <leandre@lecanact.me>
 License-Expression: GPL-3.0-only
 Project-URL: Repository, https://github.com/our-websites/yapper.py
 Project-URL: Issues, https://github.com/our-websites/yapper.py/issues
-Project-URL: Documentation, https://yapper.website/developers
+Project-URL: Documentation, https://yapin.gg/developers
+Keywords: yapper.py,yapin.py,discord.py,yapper,yapin
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10

{yapper_py-1.0.0 → yapper_py-1.2.0}/src/yapper.py.egg-info/SOURCES.txt

@@ -9,4 +9,5 @@ src/yapper.py.egg-info/dependency_links.txt
 src/yapper.py.egg-info/requires.txt
 src/yapper.py.egg-info/top_level.txt
 tests/test_api_surface.py
+tests/test_errors_and_test_event.py
 tests/test_metadata.py

{yapper_py-1.0.0 → yapper_py-1.2.0}/tests/test_api_surface.py

@@ -1,6 +1,4 @@
-import importlib.util
-import pathlib
-import unittest
+import importlib.util, pathlib, unittest
 
 
 ROOT = pathlib.Path(__file__).resolve().parents[1]

yapper_py-1.2.0/tests/test_errors_and_test_event.py

@@ -0,0 +1,46 @@
+import contextlib, importlib.util, io, pathlib, unittest
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+spec = importlib.util.spec_from_file_location("yapper_main", ROOT / "src" / "yapper" / "main.py")
+y = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(y)
+
+
+def make_bot():
+    return y.Bot("yb_test")
+
+
+class TestEventTests(unittest.TestCase):
+    def test_test_event_prints_without_listener(self):
+        bot = make_bot()
+        out = io.StringIO()
+        with contextlib.redirect_stdout(out):
+            bot.handle({"id": 1, "type": "test", "data": {}})
+        self.assertIn("test event received", out.getvalue())
+
+    def test_test_event_still_reaches_listener_and_stays_quiet(self):
+        bot = make_bot()
+        got = []
+        bot.on("test")(lambda e: got.append(e))
+        out = io.StringIO()
+        with contextlib.redirect_stdout(out):
+            bot.handle({"id": 1, "type": "test", "data": {}})
+        self.assertEqual(len(got), 1)
+        self.assertEqual(out.getvalue(), "")
+
+
+class RunErrorTests(unittest.TestCase):
+    def test_bad_token_is_printed_not_raised_as_traceback(self):
+        bot = make_bot()
+        def boom(*a, **k):
+            raise y.YapperError("bad token", 401)
+        bot.api = boom
+        out = io.StringIO()
+        with contextlib.redirect_stdout(out), self.assertRaises(SystemExit):
+            bot.run()
+        self.assertIn("could not start (401)", out.getvalue())
+        self.assertIn("Settings -> Developer", out.getvalue())
+
+
+if __name__ == "__main__":
+    unittest.main()

{yapper_py-1.0.0 → yapper_py-1.2.0}/tests/test_metadata.py

@@ -1,6 +1,4 @@
-import pathlib
-import tomllib
-import unittest
+import pathlib, tomllib, unittest
 
 
 ROOT = pathlib.Path(__file__).resolve().parents[1]

yapper_py-1.0.0/src/yapper/__init__.py

@@ -1,13 +0,0 @@
-from .main import (
-    Bot,
-    Cog,
-    YapperError,
-    btn,
-    button,
-    command,
-    link_button,
-    listener,
-    row,
-)
-
-__all__ = ["Bot", "Cog", "command", "listener", "button", "YapperError", "row", "btn", "link_button"]