Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/caching.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
4 changes: 2 additions & 2 deletions docs/frontend-and-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
69 changes: 69 additions & 0 deletions docs/live.md
Original file line number Diff line number Diff line change
@@ -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).
1 change: 1 addition & 0 deletions docs/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +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, 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) |
Expand Down
1 change: 1 addition & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ classifiers = [
]
dependencies = [
"ms-entrance>=2.0",
"wreq>=0.13",
]

[project.optional-dependencies]
Expand Down
3 changes: 3 additions & 0 deletions src/outnote/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -65,6 +66,8 @@
"CursorExpired",
"Change",
"SQLiteCache",
"LiveConnection",
"LiveEvent",
"TokenError",
"extract_text",
"html_to_text",
Expand Down
Loading
Loading