From f4c67e34bf22c2bb219515308888e9200ca30c2b Mon Sep 17 00:00:00 2001 From: PianoNic <79938743+Pianonic@users.noreply.github.com> Date: Tue, 3 Nov 2026 15:49:46 +0100 Subject: [PATCH 1/3] wip: Teams typing and live feed, waiting on a two-person test --- docs/reference.md | 1 + pyproject.toml | 1 + src/outnote/__init__.py | 3 + src/outnote/_live.py | 264 +++++++++++++++++++++++++++++++++++++ src/outnote/_native.py | 36 +++++ tests/test_live.py | 284 ++++++++++++++++++++++++++++++++++++++++ uv.lock | 4 +- 7 files changed, 592 insertions(+), 1 deletion(-) create mode 100644 src/outnote/_live.py create mode 100644 tests/test_live.py diff --git a/docs/reference.md b/docs/reference.md index 2fb67e8..8155185 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -30,6 +30,7 @@ Verified end-to-end against a live locked-down EDU tenant. | Extras | `people()`, `reminders(start, end)`, `categories()`, `mail_tips(addresses)`, `recent_files()`, `shared_with_me()` | `/me/people`, `reminderView`, `masterCategories`, `getMailTips`, `/me/drive/recent`, `/me/drive/sharedWithMe` | | Mailbox settings | `mailbox_settings()`, `auto_replies()`, `working_hours()`, `mail_rules()` | `/me/mailboxSettings`, `messageRules`, read-only, through the Teams client | | Behind an API | `outnote.api`: `ApiCache`, `ClientPool`, `respond`, `error_response` | optional, see [frontend-and-api.md](frontend-and-api.md) | +| Live Teams | `listen()`, `send_typing(chat_id)`, `clear_typing(chat_id)` | Teams' push service and chat service, undocumented, no Graph fallback | | Search | `search_emails`, `search_files`, `search_messages`, `search_people`, `search(q, entity)` | `/search/query` | | Robustness | `batch(requests)`, `delta(path, delta_link)` | `/$batch` (20 per call, 4 calls at once, throttled sub-requests retried), `/delta` | | Sync | `stream(kind, cursor)`, `SQLiteCache(path, client)` | Graph delta and Teams' sync cursors, see [caching.md](caching.md) | diff --git a/pyproject.toml b/pyproject.toml index d3fbf24..42b3041 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -47,6 +47,7 @@ classifiers = [ ] dependencies = [ "ms-entrance>=2.0", + "wreq>=0.13", ] [project.optional-dependencies] diff --git a/src/outnote/__init__.py b/src/outnote/__init__.py index 11e9584..ca29c7a 100644 --- a/src/outnote/__init__.py +++ b/src/outnote/__init__.py @@ -55,6 +55,7 @@ GraphError, OutNote, ) +from ._live import LiveConnection, LiveEvent from ._stream import Change from ._text import extract_text, html_to_text, message_text @@ -65,6 +66,8 @@ "CursorExpired", "Change", "SQLiteCache", + "LiveConnection", + "LiveEvent", "TokenError", "extract_text", "html_to_text", diff --git a/src/outnote/_live.py b/src/outnote/_live.py new file mode 100644 index 0000000..4529180 --- /dev/null +++ b/src/outnote/_live.py @@ -0,0 +1,264 @@ +"""Live Teams events over Trouter, the push connection Teams itself uses. Undocumented, so it can +change without notice. Nothing here runs unless you call `listen()`, and it keeps no state on disk. + + with note.listen() as live: + for event in live: + if event.kind == "typing": + print(event.sender_name, "is typing in", event.chat_id) + elif event.kind == "message": + print(event.sender_name, event.message["body"]["content"]) +""" + +import json +import logging +import time +import uuid +from dataclasses import dataclass +from datetime import timedelta +from typing import Any +from urllib.parse import quote, unquote, urlencode + +from ._native import message_from_native + +log = logging.getLogger("outnote.live") + +_ALLOCATE = "https://go.trouter.teams.microsoft.com/v4/a" +_REGISTRAR = "https://teams.microsoft.com/registrar/prod/V2/registrations" +_APP = "TeamsCDLWebWorker" +_TEMPLATE = "TeamsCDLWebWorker_2.7" +_VERSION = "1415/1.0.0.0" +_HEARTBEAT = 25 # seconds; the server allows about 70 +_POLL = 2 # seconds to wait for a frame, so close() takes effect quickly +_MAX_BACKOFF = 60 + + +@dataclass +class LiveEvent: + """One live event. `kind` is `typing`, `stop_typing`, `message`, `message_updated`, + `message_deleted`, `connected` (the feed is up; events may have been missed before it, so catch + up with `chat_messages` or `stream`), or `other`. `from_me` is True for your own activity. The + original event is in `raw`.""" + + kind: str + chat_id: str | None = None + sender_id: str | None = None + sender_name: str | None = None + from_me: bool = False + message: dict | None = None + raw: Any = None + + +def parse_frame(frame): + """Split a socket.io frame into `(type, ack_id, payload)`.""" + parts = frame.split(":", 3) + return parts[0], parts[1] if len(parts) > 1 else "", parts[3] if len(parts) > 3 else "" + + +def event_from(raw, me=None): + """A `LiveEvent` from one item of Trouter's `eventMessages`.""" + resource = raw.get("resource") or {} + link = resource.get("conversationLink") or "" + chat_id = unquote(link.rsplit("/", 1)[-1]) if link else None + mri = (resource.get("from") or "").rsplit("/", 1)[-1] + sender = mri.removeprefix("8:orgid:") if mri else None + name = resource.get("imdisplayname") or None + event = LiveEvent("other", chat_id, sender, name, bool(me and sender == me), None, raw) + kind = resource.get("messagetype") + if raw.get("resourceType") not in ("NewMessage", "MessageUpdate") or not kind: + return event + if kind == "Control/Typing": + event.kind = "typing" + elif kind == "Control/ClearTyping": + event.kind = "stop_typing" + elif str(kind).startswith(("Control/", "ThreadActivity/", "Event/")): + return event + else: + event.message = message_from_native(resource, chat_id) + if event.message["deletedDateTime"]: + event.kind = "message_deleted" + else: + new = raw["resourceType"] == "NewMessage" + event.kind = "message" if new else "message_updated" + return event + + +class LiveConnection: + """An iterator of `LiveEvent`s that reconnects by itself, waiting longer after each failure. Stop + it with `close()`, from another thread if needed, or by leaving the `with` block.""" + + def __init__(self, client, reconnect=True): + self.client, self.reconnect = client, reconnect + self._closed = False + self._ws = None + self._http = None + + def __enter__(self): + return self + + def __exit__(self, *exc): + self.close() + return False + + def close(self): + self._closed = True + + def __iter__(self): + failures = 0 + try: + while not self._closed: + try: + self._connect() + yield LiveEvent("connected") + failures = 0 + yield from self._frames() + except Exception as e: # noqa: BLE001 - network, auth or protocol: all mean reconnect + if not self.reconnect: + raise + log.warning("live connection failed, reconnecting: %s", e) + self._disconnect() + if not self.reconnect: + return + failures += 1 + self._sleep(min(2**failures, _MAX_BACKOFF)) + finally: + self._disconnect() + + def _sleep(self, seconds): + end = time.monotonic() + seconds + while not self._closed and time.monotonic() < end: + time.sleep(min(0.25, seconds)) + + def _request(self, method, url, headers, body=None): + """Without automatic decompression, which fails on Trouter's replies.""" + from entrance._http import Response, _headers + from wreq import Method + + kw = {"headers": {**headers, "Accept-Encoding": "identity"}} + if body: + kw["body"] = body + elif method == "POST": + kw["headers"]["Content-Length"] = "0" + with self._http.request(getattr(Method, method), url, **kw) as r: + response = Response(r.status.as_int(), _headers(r.headers), bytes(r.bytes())) + if response.status_code >= 300: + raise OSError(f"{url.split('?')[0]} answered {response.status_code}") + return response + + def _connect(self): + """Allocate a session, open the socket, and register it for chat events.""" + import wreq.blocking as wb + + self._http = wb.Client(gzip=False, brotli=False, deflate=False, zstd=False) + token = self.client._chatsvc()["headers"]["Authentication"].split("=", 1)[1] + headers = {"X-Skypetoken": token} + epid = str(uuid.uuid4()) + session = self._request("POST", f"{_ALLOCATE}?epid={epid}", headers).json() + server = session["socketio"].rstrip("/") + "/" + tc = json.dumps( + {"cv": "2024.23.01.2", "ua": "TeamsCDL", "hr": "", "v": _VERSION}, separators=(",", ":") + ) + params = { + "v": "v4", + "tc": tc, + "con_num": f"{int(time.time() * 1000)}_1", + "epid": epid, + "ccid": session.get("ccid", ""), + "auth": "true", + "timeout": "40", + **(session.get("connectparams") or {}), + } + query = urlencode(params, quote_via=quote) + shake = self._request("GET", f"{server}socket.io/1/?{query}", headers).text + sid = shake.split(":")[0] + url = f"{server.replace('https://', 'wss://')}socket.io/1/websocket/{sid}?{query}" + self._ws = self._http.websocket(url, headers=headers) + registration = { + "clientDescription": { + "appId": _APP, + "aesKey": "", + "languageId": "en-US", + "platform": "edge", + "templateKey": _TEMPLATE, + "platformUIVersion": _VERSION, + }, + "registrationId": str(uuid.uuid4()), + "nodeId": "", + "transports": {"TROUTER": [{"context": "", "path": session["surl"], "ttl": 86400}]}, + } + self._request( + "POST", + _REGISTRAR, + {**headers, "Content-Type": "application/json"}, + json.dumps(registration).encode(), + ) + + def _disconnect(self): + ws, self._ws = self._ws, None + if ws is not None: + try: + ws.close() + except Exception: # noqa: BLE001 - already gone + log.debug("closing the live socket failed", exc_info=True) + + def _send(self, text): + import wreq + + self._ws.send(wreq.Message.from_text(text)) + + def _recv(self): + message = self._ws.recv(timeout=timedelta(seconds=_POLL)) + if message is None: + return None + text = message.text + text = text() if callable(text) else text + if text is None: + return None + return text if isinstance(text, str) else bytes(text).decode("utf-8", "replace") + + def _frames(self): + me = self.client._me_id() + expires = self.client._chatsvc()["exp"] + beat = time.monotonic() + while not self._closed: + if time.time() > expires - 120: + self.client._ids.pop("chatsvc", None) # so the reconnect signs in again + raise OSError("session token is about to expire") + if time.monotonic() - beat > _HEARTBEAT: + self._send("2:::") + beat = time.monotonic() + try: + frame = self._recv() + except Exception as e: + if "imeout" in type(e).__name__ or "timed out" in str(e).lower(): + continue + raise + if not frame: + continue + kind, ack, payload = parse_frame(frame) + if kind == "0": + raise OSError("the server closed the live connection") + if kind == "2": + self._send("2:::") + elif kind == "5" and ack.endswith("+"): + self._send(f"6:::{ack.removesuffix('+')}+[]") + elif kind == "3": + yield from self._delivery(payload, me) + + def _delivery(self, payload, me): + """Trouter wraps each delivery as a request, which must be answered or it's sent again.""" + try: + delivery = json.loads(payload) + except ValueError: + log.debug("unreadable delivery ignored") + return + self._send( + "3:::" + + json.dumps({"id": delivery.get("id"), "status": 200, "headers": {}, "body": ""}) + ) + try: + body = json.loads(delivery.get("body") or "{}") + except (TypeError, ValueError): + return + items = body.get("eventMessages") or ([body] if body.get("resourceType") else []) + for raw in items: + yield event_from(raw, me) diff --git a/src/outnote/_native.py b/src/outnote/_native.py index 2b908d4..82e349a 100644 --- a/src/outnote/_native.py +++ b/src/outnote/_native.py @@ -243,6 +243,42 @@ def teams_presence(self, user_ids): "POST", f"{s['presence']}/v1/presence/getpresence/", body, scope=PRESENCE_SCOPE ) + # --- typing and live events ----------------------------------------------- + def _control(self, chat_id, kind): + if not self.native: + raise ValueError("this needs the native Teams API: a brokered client") + s = self._chatsvc() + body = {"content": "", "messagetype": kind, "contenttype": "Application/Message"} + return self.request( + "POST", + f"{s['url']}/v1/users/ME/conversations/{chat_id}/messages", + body, + headers=s["headers"], + scope=SKYPE_SCOPE, + ) + + def send_typing(self, chat_id): + """Show "typing" to the other people in a chat. The signal fades by itself, so while the user + keeps typing, call this again about every 6 seconds, as Teams does. Teams' own API, + undocumented, no Graph fallback.""" + self._control(chat_id, "Control/Typing") + + def clear_typing(self, chat_id): + """Stop showing "typing" straight away, for when the user clears what they wrote. Sending a + message ends it too.""" + self._control(chat_id, "Control/ClearTyping") + + def listen(self, reconnect=True): + """A live feed of Teams events: who's typing, new messages, edits and deletions. Iterate it, + ideally in a `with` block, and see `LiveEvent`. It reconnects by itself and yields a + `connected` event each time; anything sent while it was down is missed, so catch up with + `chat_messages` or `stream`. Uses Teams' own push service, undocumented, no Graph fallback.""" + if not self.native: + raise ValueError("this needs the native Teams API: a brokered client") + from ._live import LiveConnection + + return LiveConnection(self, reconnect) + # --- Outlook ------------------------------------------------------------ def mail_startup(self, top=25, timezone_name="UTC", conversations=True, focused=True): """What Outlook on the web loads at boot, in one request: `findConversation` (the first diff --git a/tests/test_live.py b/tests/test_live.py new file mode 100644 index 0000000..5a402c3 --- /dev/null +++ b/tests/test_live.py @@ -0,0 +1,284 @@ +"""Typing and the live feed, with a fake socket. No network.""" + +import json +import threading +import time + +import pytest + +import outnote +from outnote import _live +from outnote._live import LiveConnection, LiveEvent, event_from, parse_frame + +ME = "11111111-1111-1111-1111-111111111111" +BOB = "22222222-2222-2222-2222-222222222222" +CHAT = "19:abc@thread.v2" +AUTHZ = { + "tokens": {"skypeToken": "sk", "expiresIn": 3600}, + "regionGtms": {"chatService": "https://chat.test"}, +} + + +def resource(kind="Text", sender=BOB, **more): + return { + "id": "1", + "messagetype": kind, + "content": "hi", + "from": f"https://x/contacts/8:orgid:{sender}", + "imdisplayname": "Bob", + "conversationLink": f"https://x/v1/users/ME/conversations/{CHAT}", + "originalarrivaltime": "2026-01-01T00:00:00.000Z", + **more, + } + + +def raw(kind="Text", event="NewMessage", **more): + return {"resourceType": event, "resource": resource(kind, **more)} + + +# --- event parsing ---------------------------------------------------------------- +def test_typing_events(): + e = event_from(raw("Control/Typing"), ME) + assert (e.kind, e.chat_id, e.sender_id, e.sender_name) == ("typing", CHAT, BOB, "Bob") + assert e.from_me is False and e.message is None + assert event_from(raw("Control/ClearTyping"), ME).kind == "stop_typing" + + +def test_message_events_use_graph_shape(): + e = event_from(raw("RichText/Html"), ME) + assert e.kind == "message" and e.message["chatId"] == CHAT + assert e.message["body"]["contentType"] == "html" + assert event_from(raw(event="MessageUpdate"), ME).kind == "message_updated" + gone = raw(event="MessageUpdate", properties={"deletetime": "1793692800000"}) + assert event_from(gone, ME).kind == "message_deleted" + + +def test_own_activity_is_marked(): + assert event_from(raw("Control/Typing", sender=ME), ME).from_me is True + + +@pytest.mark.parametrize( + "item", + [ + raw("ThreadActivity/AddMember"), + raw("Control/Something"), + {"resourceType": "ThreadUpdate", "resource": {"id": "x"}}, + {"resourceType": "NewMessage"}, + ], +) +def test_other_events_stay_other_and_keep_raw(item): + e = event_from(item, ME) + assert e.kind == "other" and e.raw is item and e.message is None + + +def test_encoded_chat_ids_are_decoded(): + item = raw() + item["resource"]["conversationLink"] = "https://x/conversations/19%3Aabc%40thread.v2" + assert event_from(item).chat_id == CHAT + + +def test_parse_frame(): + assert parse_frame("1::") == ("1", "", "") + assert parse_frame('3:::{"a":1}') == ("3", "", '{"a":1}') + assert parse_frame('5:7+::{"name":"x:y"}') == ("5", "7+", '{"name":"x:y"}') + + +# --- the connection --------------------------------------------------------------- +class FakeSocket: + def __init__(self, frames): + self.frames, self.sent, self.closed = list(frames), [], False + + def recv(self, timeout=None): + if self.frames: + item = self.frames.pop(0) + if isinstance(item, Exception): + raise item + return type("M", (), {"text": item})() + time.sleep(0.01) + return None + + def send(self, message): + self.sent.append(message) + + def close(self): + self.closed = True + + +def delivery(*items, id=9): + body = json.dumps({"eventMessages": list(items)}) + return "3:::" + json.dumps({"id": id, "method": "POST", "url": "/x", "body": body}) + + +@pytest.fixture +def connected(monkeypatch): + """A LiveConnection whose _connect installs the next fake socket.""" + client = outnote.OutNote("tok") + client._ids["me"] = ME + client._ids["chatsvc"] = {"exp": time.time() + 3600, "headers": {}, "url": "https://chat.test"} + sockets = [] + + def make(frames_per_connection, **kw): + queue = [FakeSocket(f) for f in frames_per_connection] + live = LiveConnection(client, **kw) + + def connect(): + if not queue: + raise OSError("no more connections") + live._ws = queue.pop(0) + sockets.append(live._ws) + + monkeypatch.setattr(live, "_connect", connect) + monkeypatch.setattr(live, "_send", lambda text: live._ws.send(text)) + monkeypatch.setattr(live, "_sleep", lambda s: None) + return live, sockets + + return make + + +def take(live, n): + out = [] + for event in live: + out.append(event) + if len(out) >= n: + live.close() + return out + + +def test_events_arrive_and_deliveries_are_acknowledged(connected): + live, sockets = connected([["1::", delivery(raw("Control/Typing"))]]) + events = take(live, 2) + assert [e.kind for e in events] == ["connected", "typing"] + ack = json.loads(sockets[0].sent[0].split(":::", 1)[1]) + assert ack == {"id": 9, "status": 200, "headers": {}, "body": ""} + + +def test_heartbeats_and_acks_are_answered(connected): + live, sockets = connected([["2::", '5:4+::{"name":"trouter.connected"}', delivery(raw())]]) + take(live, 2) + assert "2:::" in sockets[0].sent and "6:::4+[]" in sockets[0].sent + + +def test_bad_deliveries_are_survived(connected): + bad = "3:::" + json.dumps({"id": 1, "body": "not json"}) + live, _ = connected([["3:::not json", bad, delivery(raw())]]) + assert [e.kind for e in take(live, 2)] == ["connected", "message"] + + +def test_it_reconnects_and_says_so(connected): + live, sockets = connected([[OSError("dropped")], ["1::", delivery(raw())]]) + events = take(live, 3) + assert [e.kind for e in events] == ["connected", "connected", "message"] + assert sockets[0].closed + + +def test_server_disconnect_frame_reconnects(connected): + live, _ = connected([["0::"], [delivery(raw())]]) + assert [e.kind for e in take(live, 3)] == ["connected", "connected", "message"] + + +def test_failing_connections_back_off_and_stop_on_close(connected, monkeypatch): + live, _ = connected([]) + waits = [] + + def sleep(seconds): + waits.append(seconds) + if len(waits) == 8: + live.close() + + monkeypatch.setattr(live, "_sleep", sleep) + assert list(live) == [] + assert waits[:3] == [2, 4, 8] and max(waits) == _live._MAX_BACKOFF + + +def test_reconnect_can_be_turned_off(connected): + live, _ = connected([[OSError("dropped")]], reconnect=False) + with pytest.raises(OSError): + list(live) + + +def test_timeouts_are_not_failures(connected): + class ReadTimeout(Exception): + pass + + live, sockets = connected([[ReadTimeout("x"), delivery(raw())]]) + assert [e.kind for e in take(live, 2)] == ["connected", "message"] + assert len(sockets) == 1 + + +def test_close_from_another_thread_stops_it(connected): + live, sockets = connected([[]]) + got = [] + t = threading.Thread(target=lambda: got.extend(live)) + t.start() + time.sleep(0.1) + live.close() + t.join(3) + assert not t.is_alive() and [e.kind for e in got] == ["connected"] and sockets[0].closed + + +def test_context_manager_closes(connected): + live, _ = connected([[]]) + with live: + pass + assert live._closed + + +def test_an_expiring_session_reconnects_with_a_new_one(connected, monkeypatch): + live, sockets = connected([[], [delivery(raw())]]) + client = live.client + client._ids["chatsvc"]["exp"] = time.time() + 90 # valid, but inside the 120 s margin + monkeypatch.setattr(client, "request", lambda *a, **k: AUTHZ) + events = take(live, 3) + assert [e.kind for e in events] == ["connected", "connected", "message"] + assert client._ids["chatsvc"]["exp"] > time.time() + 3000 # signed in again + assert len(sockets) == 2 + + +# --- sending typing --------------------------------------------------------------- +def brokered(monkeypatch): + c = outnote.OutNote(lambda client_id, scope=None: "tok") + calls = [] + + def request(method, path, body=None, **kw): + calls.append({"method": method, "path": path, "body": body, **kw}) + return AUTHZ if "authz" in path else {"OriginalArrivalTime": 1} + + monkeypatch.setattr(c, "request", request) + return c, calls + + +@pytest.mark.parametrize( + ("method", "kind"), + [("send_typing", "Control/Typing"), ("clear_typing", "Control/ClearTyping")], +) +def test_typing_is_sent_to_that_chat(monkeypatch, method, kind): + c, calls = brokered(monkeypatch) + getattr(c, method)(CHAT) + call = calls[-1] + assert call["method"] == "POST" and call["path"].endswith(f"/conversations/{CHAT}/messages") + assert call["body"] == { + "content": "", + "messagetype": kind, + "contenttype": "Application/Message", + } + assert call["headers"] == {"Authentication": "skypetoken=sk"} + + +@pytest.mark.parametrize("call", ["send_typing", "clear_typing"]) +def test_typing_needs_a_brokered_client(call): + with pytest.raises(ValueError): + getattr(outnote.OutNote("tok"), call)(CHAT) + + +def test_listen_needs_a_brokered_client(): + with pytest.raises(ValueError): + outnote.OutNote("tok").listen() + + +def test_listen_returns_a_connection_without_connecting(monkeypatch): + c, calls = brokered(monkeypatch) + assert isinstance(c.listen(), LiveConnection) and calls == [] + + +def test_exports(): + assert outnote.LiveEvent is LiveEvent and outnote.LiveConnection is LiveConnection diff --git a/uv.lock b/uv.lock index 26d9de1..4a7d15f 100644 --- a/uv.lock +++ b/uv.lock @@ -429,10 +429,11 @@ wheels = [ [[package]] name = "outnote" -version = "2.0.0" +version = "2.1.1" source = { editable = "." } dependencies = [ { name = "ms-entrance" }, + { name = "wreq" }, ] [package.optional-dependencies] @@ -451,6 +452,7 @@ dev = [ requires-dist = [ { name = "ms-entrance", specifier = ">=2.0" }, { name = "pypdf", marker = "extra == 'pdf'", specifier = ">=4" }, + { name = "wreq", specifier = ">=0.13" }, ] provides-extras = ["pdf"] From 3012bf2b5ca161e4ce3b9738aebd4319f1a8e92e Mon Sep 17 00:00:00 2001 From: PianoNic <79938743+Pianonic@users.noreply.github.com> Date: Tue, 3 Nov 2026 16:03:53 +0100 Subject: [PATCH 2/3] wip: live presence --- src/outnote/_live.py | 61 ++++++++++++++++++++++++++++++++++--- src/outnote/_native.py | 7 +++-- tests/test_live.py | 69 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 129 insertions(+), 8 deletions(-) diff --git a/src/outnote/_live.py b/src/outnote/_live.py index 4529180..a52b50e 100644 --- a/src/outnote/_live.py +++ b/src/outnote/_live.py @@ -18,7 +18,8 @@ from typing import Any from urllib.parse import quote, unquote, urlencode -from ._native import message_from_native +from ._base import GraphError +from ._native import PRESENCE_SCOPE, message_from_native log = logging.getLogger("outnote.live") @@ -35,9 +36,10 @@ @dataclass class LiveEvent: """One live event. `kind` is `typing`, `stop_typing`, `message`, `message_updated`, - `message_deleted`, `connected` (the feed is up; events may have been missed before it, so catch - up with `chat_messages` or `stream`), or `other`. `from_me` is True for your own activity. The - original event is in `raw`.""" + `message_deleted`, `presence` (someone you asked to watch: see `sender_id`, `availability` and + `activity`), `connected` (the feed is up; events may have been missed before it, so catch up with + `chat_messages` or `stream`), or `other`. `from_me` is True for your own activity. The original + event is in `raw`.""" kind: str chat_id: str | None = None @@ -46,6 +48,8 @@ class LiveEvent: from_me: bool = False message: dict | None = None raw: Any = None + availability: str | None = None + activity: str | None = None def parse_frame(frame): @@ -82,12 +86,32 @@ def event_from(raw, me=None): return event +def presence_events(body, me=None): + """`LiveEvent`s from a Trouter presence delivery, which starts with everyone's current state.""" + events = [] + for item in body.get("presence") or []: + state = item.get("presence") or {} + user = (item.get("mri") or "").removeprefix("8:orgid:") or None + events.append( + LiveEvent( + "presence", + sender_id=user, + from_me=bool(me and user == me), + raw=item, + availability=state.get("availability"), + activity=state.get("activity"), + ) + ) + return events + + class LiveConnection: """An iterator of `LiveEvent`s that reconnects by itself, waiting longer after each failure. Stop it with `close()`, from another thread if needed, or by leaving the `with` block.""" - def __init__(self, client, reconnect=True): + def __init__(self, client, reconnect=True, presence=()): self.client, self.reconnect = client, reconnect + self.presence = list(presence) self._closed = False self._ws = None self._http = None @@ -191,6 +215,30 @@ def _connect(self): {**headers, "Content-Type": "application/json"}, json.dumps(registration).encode(), ) + if self.presence: + self._watch_presence(epid, session["surl"]) + + def _watch_presence(self, epid, trouter_uri): + """Ask Teams to push these people's status here. This only reads: it doesn't publish your + own status, so listening doesn't make you look online.""" + body = { + "trouterUri": trouter_uri, + "shouldPurgePreviousSubscriptions": True, + "subscriptionsToAdd": [{"mri": f"8:orgid:{u}", "source": "ups"} for u in self.presence], + "subscriptionsToRemove": [], + } + service = self.client._chatsvc()["presence"] + url = f"{service}/v1/pubsub/subscriptions/{epid}" + headers = { # the service requires these + "x-ms-client-user-agent": "Teams-V2-Web", + "x-ms-correlation-id": str(uuid.uuid4()), + "x-ms-client-version": _VERSION, + "x-ms-endpoint-id": epid, + } + try: + self.client.request("POST", url, body, headers=headers, scope=PRESENCE_SCOPE) + except GraphError as e: # messages and typing still work without it + log.warning("could not watch presence: %s", e) def _disconnect(self): ws, self._ws = self._ws, None @@ -259,6 +307,9 @@ def _delivery(self, payload, me): body = json.loads(delivery.get("body") or "{}") except (TypeError, ValueError): return + if body.get("presence"): + yield from presence_events(body, me) + return items = body.get("eventMessages") or ([body] if body.get("resourceType") else []) for raw in items: yield event_from(raw, me) diff --git a/src/outnote/_native.py b/src/outnote/_native.py index 82e349a..0e45ad7 100644 --- a/src/outnote/_native.py +++ b/src/outnote/_native.py @@ -268,8 +268,9 @@ def clear_typing(self, chat_id): message ends it too.""" self._control(chat_id, "Control/ClearTyping") - def listen(self, reconnect=True): - """A live feed of Teams events: who's typing, new messages, edits and deletions. Iterate it, + def listen(self, reconnect=True, presence=()): + """A live feed of Teams events: who's typing, new messages, edits and deletions, plus the + online status of the user ids in `presence`, starting with their current state. Iterate it, ideally in a `with` block, and see `LiveEvent`. It reconnects by itself and yields a `connected` event each time; anything sent while it was down is missed, so catch up with `chat_messages` or `stream`. Uses Teams' own push service, undocumented, no Graph fallback.""" @@ -277,7 +278,7 @@ def listen(self, reconnect=True): raise ValueError("this needs the native Teams API: a brokered client") from ._live import LiveConnection - return LiveConnection(self, reconnect) + return LiveConnection(self, reconnect, presence) # --- Outlook ------------------------------------------------------------ def mail_startup(self, top=25, timezone_name="UTC", conversations=True, focused=True): diff --git a/tests/test_live.py b/tests/test_live.py index 5a402c3..b8716ea 100644 --- a/tests/test_live.py +++ b/tests/test_live.py @@ -234,6 +234,75 @@ def test_an_expiring_session_reconnects_with_a_new_one(connected, monkeypatch): assert len(sockets) == 2 +# --- presence --------------------------------------------------------------------- +def presence_delivery(): + body = { + "isSnapshot": True, + "presence": [ + { + "mri": f"8:orgid:{BOB}", + "presence": {"availability": "Offline", "activity": "OffWork"}, + }, + {"mri": f"8:orgid:{ME}", "presence": {"availability": "Available"}}, + ], + } + return "3:::" + json.dumps({"id": 2, "url": "/unifiedPresence", "body": json.dumps(body)}) + + +def test_presence_events(connected): + live, sockets = connected([[presence_delivery()]]) + events = take(live, 3) + assert [e.kind for e in events] == ["connected", "presence", "presence"] + assert (events[1].sender_id, events[1].availability, events[1].activity) == ( + BOB, + "Offline", + "OffWork", + ) + assert events[1].from_me is False and events[2].from_me is True + assert '"id": 2' in sockets[0].sent[0] # acknowledged like any delivery + + +def test_watching_presence_subscribes_without_publishing(monkeypatch): + c = outnote.OutNote(lambda client_id, scope=None: "t") + c._ids["chatsvc"] = { + "presence": "https://ups.test", + "url": "u", + "headers": {}, + "exp": time.time() + 999, + } + calls = [] + monkeypatch.setattr(c, "request", lambda *a, **k: calls.append((a, k)) or {}) + LiveConnection(c, presence=[BOB])._watch_presence("ep", "https://trouter/f/1/") + (method, url, body), kw = calls[0] + assert method == "POST" and url == "https://ups.test/v1/pubsub/subscriptions/ep" + assert body["trouterUri"] == "https://trouter/f/1/" + assert body["subscriptionsToAdd"] == [{"mri": f"8:orgid:{BOB}", "source": "ups"}] + assert kw["scope"] == "https://presence.teams.microsoft.com/.default" + assert len(calls) == 1 # never touches /me/endpoints, which would publish your own status + + +def test_a_failed_presence_subscription_does_not_stop_the_feed(monkeypatch): + c = outnote.OutNote(lambda client_id, scope=None: "t") + c._ids["chatsvc"] = { + "presence": "https://ups.test", + "url": "u", + "headers": {}, + "exp": time.time() + 999, + } + + def refused(*a, **k): + raise outnote.GraphError(400, "no") + + monkeypatch.setattr(c, "request", refused) + LiveConnection(c, presence=[BOB])._watch_presence("ep", "https://t/") # logs, doesn't raise + + +def test_no_presence_requested_means_no_subscription(monkeypatch): + c = outnote.OutNote(lambda client_id, scope=None: "t") + assert LiveConnection(c).presence == [] + assert c.listen.__defaults__ == (True, ()) + + # --- sending typing --------------------------------------------------------------- def brokered(monkeypatch): c = outnote.OutNote(lambda client_id, scope=None: "tok") From 2547d7ba43dcd4ca82665c8c9944c809e8284a2b Mon Sep 17 00:00:00 2001 From: PianoNic <79938743+Pianonic@users.noreply.github.com> Date: Wed, 4 Nov 2026 15:15:20 +0100 Subject: [PATCH 3/3] Added docs for live Teams events --- docs/caching.md | 2 +- docs/frontend-and-api.md | 4 +-- docs/live.md | 69 ++++++++++++++++++++++++++++++++++++++++ docs/reference.md | 2 +- src/outnote/_live.py | 2 +- uv.lock | 2 +- 6 files changed, 75 insertions(+), 6 deletions(-) create mode 100644 docs/live.md diff --git a/docs/caching.md b/docs/caching.md index 25189d4..3b31025 100644 --- a/docs/caching.md +++ b/docs/caching.md @@ -111,7 +111,7 @@ A large first sync can take a while: about 40 seconds for 14,000 OneDrive files ## Keeping it fresh -There's no push yet, so poll. A sync that finds nothing is cheap, so a short loop is fine: +For Teams, [`note.listen()`](live.md) pushes events live. Everything else needs polling. A sync that finds nothing is cheap, so a short loop is fine: ```python while True: diff --git a/docs/frontend-and-api.md b/docs/frontend-and-api.md index 0f1e0fd..e45f9fc 100644 --- a/docs/frontend-and-api.md +++ b/docs/frontend-and-api.md @@ -619,8 +619,8 @@ Register it from your page with `navigator.serviceWorker.register("/sw.js")`. computer could read the previous user's mail. IndexedDB isn't encrypted. - **Respect `Retry-After`.** If `error.retryAfter` is set, wait that long before trying again. - **Don't poll too often.** `keepFresh` stops while the tab is hidden, and 30 seconds is a fair start. -- **There's no push here.** Teams and Outlook get updates over their own push connections, so this approach - has a delay up to your polling interval. +- **There's no push here.** This approach has a delay up to your polling interval. For Teams, + [`note.listen()`](live.md) can deliver events live, if your API forwards them to the browser. ## Choosing the times diff --git a/docs/live.md b/docs/live.md new file mode 100644 index 0000000..e6a291c --- /dev/null +++ b/docs/live.md @@ -0,0 +1,69 @@ +# Live Teams events + +`note.listen()` gives you a live feed of Teams events: messages, edits, deletions, who's typing and who's +online. It uses Trouter, the push connection Teams itself uses, so events arrive without polling. In testing, +a message reached the client in about 300 ms. + +**This is undocumented and can change without notice.** There's no Graph fallback, so keep a normal way to +read data too. It needs a client from `authenticate` or `from_refresh_token`. + +```python +with note.listen(presence=[user_id]) as live: + for event in live: + if event.kind == "connected": + catch_up() # anything sent while disconnected was missed + elif event.kind == "message" and not event.from_me: + print(event.sender_name, outnote.message_text(event.message)) + elif event.kind == "typing": + show_typing(event.chat_id, event.sender_id) + elif event.kind == "presence": + show_status(event.sender_id, event.availability) +``` + +`listen()` blocks while you iterate it, so run it in a background thread if your app does other work. Call +`live.close()` to stop it, from any thread. It reconnects by itself, waiting longer after each failure. + +## Events + +| `event.kind` | Means | Useful fields | +|---|---|---| +| `connected` | The feed is up, on first connect and after every reconnect | | +| `message` | A new message | `chat_id`, `sender_id`, `sender_name`, `from_me`, `message` | +| `message_updated` | A message changed | same as `message` | +| `message_deleted` | A message was deleted | `chat_id`, `message` | +| `typing` | Someone is typing | `chat_id`, `sender_id`, `from_me` | +| `stop_typing` | Someone stopped | `chat_id`, `sender_id` | +| `presence` | Status of someone in `presence=` | `sender_id`, `availability`, `activity`, `from_me` | +| `other` | Anything else, such as read receipts and member changes | `chat_id`, `raw` | + +`message` is in Graph's shape, and the original event is always in `raw`. + +Things to know, from testing: + +- **Typing events usually have no name.** `sender_name` was empty on them, so look the name up from the id, + for example with `chat_members()`. Messages do include it. +- **Hide the typing indicator yourself.** While someone types, events arrived about every 4 seconds, and + `stop_typing` never arrived in testing. So hide it after about 6 seconds without a new event, or when a + message arrives from them. +- **You don't see your own typing.** It wasn't echoed back in testing. +- **`presence` starts with everyone's current state.** Listening doesn't publish your own status, so it + doesn't make you look online. Status changes were only seen live for the signed-in user, and someone + who was active in a chat stayed reported as `Offline`, so treat status as a hint. +- **Tokens renew by themselves.** The feed reconnects shortly before its session token expires, which can + leave a short gap. Catch up on `connected`. + +## Showing that you're typing + +```python +note.send_typing(chat_id) # the other people see you typing +note.clear_typing(chat_id) # stop straight away, if the user clears what they wrote +``` + +The signal fades by itself, so call `send_typing` about every 6 seconds while the user types, as Teams does. +Sending a message ends it too. **Other people really see this**, so only send it when the user is typing. + +## Behind an API + +`listen()` holds one long-lived connection per user, so it belongs in a background service, not a request +handler. Forward events to your frontend with something like WebSockets or server-sent events, and check +that each one only goes to the user it belongs to. See [frontend-and-api.md](frontend-and-api.md). diff --git a/docs/reference.md b/docs/reference.md index 4c1d4e7..917bc7e 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -32,7 +32,7 @@ Verified end-to-end against a live locked-down EDU tenant. | Extras | `people()`, `reminders(start, end)`, `categories()`, `mail_tips(addresses)`, `recent_files()`, `shared_with_me()` | `/me/people`, `reminderView`, `masterCategories`, `getMailTips`, `/me/drive/recent`, `/me/drive/sharedWithMe` | | Mailbox settings | `mailbox_settings()`, `auto_replies()`, `working_hours()`, `mail_rules()` | `/me/mailboxSettings`, `messageRules`, read-only, through the Teams client | | Behind an API | `outnote.api`: `ApiCache`, `ClientPool`, `respond`, `error_response` | optional, see [frontend-and-api.md](frontend-and-api.md) | -| Live Teams | `listen()`, `send_typing(chat_id)`, `clear_typing(chat_id)` | Teams' push service and chat service, undocumented, no Graph fallback | +| Live Teams | `listen()`, `send_typing(chat_id)`, `clear_typing(chat_id)` | Teams' push service and chat service, undocumented, no Graph fallback, see [live.md](live.md) | | Search | `search_emails`, `search_files`, `search_messages`, `search_people`, `search(q, entity)` | `/search/query` | | Robustness | `batch(requests)`, `delta(path, delta_link)` | `/$batch` (20 per call, 4 calls at once, throttled sub-requests retried), `/delta` | | Sync | `stream(kind, cursor)`, `SQLiteCache(path, client)` | Graph delta and Teams' sync cursors, see [caching.md](caching.md) | diff --git a/src/outnote/_live.py b/src/outnote/_live.py index a52b50e..f4d5cd0 100644 --- a/src/outnote/_live.py +++ b/src/outnote/_live.py @@ -4,7 +4,7 @@ with note.listen() as live: for event in live: if event.kind == "typing": - print(event.sender_name, "is typing in", event.chat_id) + print(event.sender_id, "is typing in", event.chat_id) elif event.kind == "message": print(event.sender_name, event.message["body"]["content"]) """ diff --git a/uv.lock b/uv.lock index 4a7d15f..c3ca98c 100644 --- a/uv.lock +++ b/uv.lock @@ -429,7 +429,7 @@ wheels = [ [[package]] name = "outnote" -version = "2.1.1" +version = "2.2.1" source = { editable = "." } dependencies = [ { name = "ms-entrance" },