@patimweb/pi-teams 1.2.0 → 1.3.0

package/README.md

@@ -7,6 +7,8 @@ from your account, in your name, in the right thread. Multiple Teams accounts
 and multiple company tenants live side by side, and a configuration file
 decides exactly which teams, channels, chats and people pi may touch.
 
+![pi-teams in the pi coding agent](screenshot.png)
+
 ## Installation
 
 ```bash
@@ -414,7 +416,8 @@ teams_permissions:
 | Tool | Description |
 |------|-------------|
 | `teams_inbox` | Chats with new messages plus recent mentions of you |
-| `teams_list_chats` | Recent chats with a preview of the last message || `teams_read_chat` | Messages of one chat |
+| `teams_list_chats` | Recent chats with a preview of the last message |
+| `teams_read_chat` | Messages of one chat |
 | `teams_list_teams` | Teams you belong to |
 | `teams_list_channels` | Channels of a team |
 | `teams_read_channel` | Posts in a channel |
@@ -424,6 +427,7 @@ teams_permissions:
 | `teams_find_user` | Directory lookup by name, e-mail or UPN |
 | `teams_list_files` | Files in a channel's SharePoint folder |
 | `teams_get_presence` | Your status, a colleague's, or a whole chat's |
+| `teams_availability` | When several people are all free, from calendar free/busy |
 | `teams_list_meetings` | Calendar events and meetings in a range |
 | `teams_get_meeting` | One meeting in full |
 
@@ -436,14 +440,23 @@ teams_permissions:
 | `teams_send_channel_message` | Post in a channel as you |
 | `teams_reply_channel_message` | Reply inside an existing thread |
 | `teams_react` | Add or remove an emoji reaction |
+| `teams_mark_read` | Mark a chat as read (or unread again) — the natural end of a catch-up |
+| `teams_update_message` | Edit a message you already sent |
+| `teams_chat_members` | Add someone to a group chat, or remove them |
 | `teams_delete_message` | Soft-delete (or restore) a message you sent |
-| `teams_create_channel` | Add a channel to a team |
 | `teams_set_presence` | Set your Teams status |
 | `teams_set_status_message` | Set the note under your name |
 | `teams_create_meeting` | Schedule a Teams meeting with invitations |
 | `teams_update_meeting` | Change a meeting you organize |
+| `teams_respond_invite` | Accept, decline or tentatively accept an invitation |
 | `teams_cancel_meeting` | Cancel a meeting |
 
+Editing and deleting apply to **chat** messages. A channel post cannot be
+created, edited or deleted through Graph with the permissions pi asks for
+(`Channel.Create`, `ChannelMessage.ReadWrite`) — that stays in the Teams client.
+Posting and replying in channels, and reacting to channel messages, work as
+usual.
+
 ## Commands
 
 | Command | Description |
@@ -464,6 +477,7 @@ teams_permissions:
 | `/teams-channel-digest` | Decisions, open questions and action items in a channel |
 | `/teams-standup` | Draft and post a standup update |
 | `/teams-meeting-prep` | Context and talking points for your next meeting |
+| `/teams-schedule` | Find a time everyone is free and book it |
 | `/teams-doctor` | Guided troubleshooting |
 
 ---
@@ -558,6 +572,9 @@ middle.
   (`prompt.ts`).
 - **`src/utils/formatting.ts`** — domain types → display strings. Pure.
 - **`src/utils/richtext.ts`** — markdown → the HTML subset Teams renders. Pure.
+- **`src/utils/slots.ts`** — availability view → the free slots everybody
+  shares. Pure, and the part of scheduling that can be wrong without looking
+  wrong.
 - **`src/safety/`** — the three gates and the audit log.
 - **`src/tools/`** — one module per tool.
 - **`src/extension/index.ts`** — registration, commands, the `tool_call`
@@ -572,8 +589,9 @@ npm test
 ```
 
 Tests cover the pure logic — scope matching, the config cascade, message body
-construction, markdown rendering, HTML flattening, the listen-mode decision
-rules, the safety gates — and run without a tenant or a network connection.
+construction, markdown rendering, HTML flattening, free-slot arithmetic, the
+listen-mode decision rules, the safety gates — and run without a tenant or a
+network connection.
 
 ## Troubleshooting
 

package/docs/entra-app-registration.md

@@ -104,6 +104,31 @@ requests them and rejects them in an explicit scope list.
 **What is not needed:** no client secret, no certificate, no redirect URI beyond
 step 2, no application (as opposed to delegated) permissions.
 
+### Optional: one capability that needs one more permission
+
+Everything above is what pi asks for by default. One action stays off until you
+add the scope — to this list **and** to `scopes` in `pi-teams.json` — and sign in
+again:
+
+| Permission | Unlocks | Consent |
+|---|---|---|
+| `ChatMember.ReadWrite` | removing someone from a chat (`teams_chat_members`) | user |
+
+Without it the tool answers with the exact scope it is missing instead of
+failing at Graph with a consent error. Editing and deleting chat messages,
+adding chat members and answering invitations all work with the default set.
+
+**Deliberately not requested:** `Channel.Create` and
+`ChannelMessage.ReadWrite`. They would unlock creating channels and editing or
+deleting a **channel** post, and pi is built not to depend on permissions that
+may never be granted. Channel posts are created, edited and deleted in the Teams
+client; posting, replying and reacting in channels work without them.
+
+**Also not covered:** `findMeetingTimes` and anything that reads another person's
+*appointments* need `Calendars.Read.Shared`. `teams_availability` uses
+`getSchedule` instead, which is free/busy only — no extra consent, and no view
+of what people are actually doing.
+
 ## 4. Consent
 
 **API permissions** → **Grant admin consent** — only for the two scopes that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patimweb/pi-teams",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Microsoft Teams integration for pi coding agent — acts fully as the signed-in user across multiple accounts and tenants: chats, channels, meetings, presence, with configurable guardrails",
   "keywords": [
     "pi-package",

package/prompts/teams-schedule.md

@@ -0,0 +1,23 @@
+---
+description: Find a time everyone is free and book the meeting
+argument-hint: "[who, what, how long]"
+---
+Organize a Teams meeting: $@
+
+1. Work out who has to be there. Resolve unclear names with `teams_find_user` —
+   never guess an e-mail address. Ask me for anything you cannot derive from the
+   request.
+
+2. Run `teams_availability` with those people and the meeting length (30 minutes
+   unless I said otherwise). If it finds nothing, widen the window with
+   `start`/`end` before giving up, and tell me what you tried.
+
+3. Show me two or three slots that fit, as weekday, date and time. **Do not book
+   anything yet.**
+
+4. Once I pick one, create it with `teams_create_meeting` in my time zone, with a
+   subject that says what the meeting is about. Confirm the slot, the people and
+   the subject in one line. Offer to add two or three lines of context from
+   `teams_search_messages` to the invitation body — only if I say yes.
+
+Do not invite anyone who was not named, and do not answer any invitation.

package/skills/teams-collaboration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: teams-collaboration
-description: Microsoft Teams chats, channels, meetings and presence, acting as the signed-in user. Use when the user asks to read, search, summarize, send or reply to Teams messages; to catch up on what they missed; to post in a channel or a thread; to start a chat; to react to a message; to check or set their Teams status; to see who is available; to schedule, change or cancel a Teams meeting; or to make pi notice incoming Teams messages on its own (listen mode). Also covers how to format a message for a chat rather than a document, multiple Teams accounts and multiple company tenants, and the allow/deny rules that decide what pi may touch.
+description: Microsoft Teams chats, channels, meetings and presence, acting as the signed-in user. Use when the user asks to read, search, summarize, send, edit, retract or reply to Teams messages; to add or remove someone from a chat; to catch up on what they missed and clear it; to post in a channel or a thread; to react to a message; to mark a chat read or unread; to check or set their Teams status; to see who is available; to find a time everyone is free; to schedule, change, answer, or cancel a Teams meeting; or to make pi notice incoming Teams messages on its own (listen mode). Also covers how to format a message for a chat rather than a document, multiple Teams accounts and multiple company tenants, and the allow/deny rules that decide what pi may touch.
 ---
 
 # Microsoft Teams
@@ -47,6 +47,20 @@ rule set. Show them the rule, do not work around it, and do not try a different
 tool to achieve the same thing. `teams_permissions` with `action: "test"`
 checks a target without touching it.
 
+## When a tool says a scope is missing
+
+One optional action needs a permission the account does not request by default:
+removing someone from a **chat** (`ChatMember.ReadWrite`). The tool names the
+exact scope. Pass that sentence on as the fix — add it to `scopes` in
+`pi-teams.json`, sign in again — or do it in Teams. Do not look for a roundabout
+way to achieve the same thing, and do not report it as a permission bug.
+
+A few things cannot be done at all with the permissions pi asks for: creating a
+channel, and editing or deleting a **channel** post. Those need
+`Channel.Create` / `ChannelMessage.ReadWrite`, they are not requested, and they
+are not assumed to be grantable. Say so plainly and point at the Teams client
+instead of trying anyway.
+
 ## Tools
 
 ### Session
@@ -76,6 +90,7 @@ checks a target without touching it.
 | `teams_find_user` | Resolving a first name to a real person |
 | `teams_list_files` | Files shared in a channel |
 | `teams_get_presence` | Is someone available right now |
+| `teams_availability` | "When are we all free?" — before booking, not after |
 | `teams_list_meetings` / `teams_get_meeting` | Calendar and meeting details |
 
 ### Writing
@@ -87,10 +102,13 @@ checks a target without touching it.
 | `teams_send_channel_message` | Posting a new channel message |
 | `teams_reply_channel_message` | Answering inside an existing thread |
 | `teams_react` | Adding or removing an emoji reaction |
+| `teams_update_message` | Fixing a message the user already sent |
+| `teams_chat_members` | Bringing someone into a group chat, or taking them out |
+| `teams_mark_read` | Clearing the unread marker after a catch-up |
 | `teams_delete_message` | Taking back something the user sent |
-| `teams_create_channel` | Adding a channel to a team |
 | `teams_set_presence` / `teams_set_status_message` | Changing the user's status |
 | `teams_create_meeting` / `teams_update_meeting` / `teams_cancel_meeting` | Scheduling work |
+| `teams_respond_invite` | Accepting, declining or tentatively answering an invitation |
 | `teams_watch` | Letting pi notice incoming messages on its own |
 
 ## How to write as the user
@@ -187,6 +205,77 @@ Before replying anywhere, read the recent messages first. It prevents
 answering a question that was already answered, and it is what tells you the
 tone to match.
 
+## Read state
+
+`teams_mark_read` moves the user's read cursor on a **chat** — the same thing
+as opening it, or re-marking it unread, in the app. Two rules:
+
+- It is a **write**, and it goes through the safety gates like any other. Mark
+  a chat read when the user asks, or when they clearly want the list cleared —
+  not on your own initiative after reading it.
+- Where the tenant shows **read receipts**, the sender can see that the chat was
+  opened. That is not a reason to refuse, only a reason not to do it silently.
+
+Channels have no equivalent: channel posts cannot be marked read or unread
+through Graph, so "mark the channel as read" is done in the Teams client.
+
+## Correcting a message
+
+Both actions work on **chat** messages the user themselves sent, which is also
+the only case that makes sense: pi wrote them in the user's name. A channel post
+cannot be edited or deleted with the permissions pi asks for — for that, point
+at the Teams client.
+
+- **`teams_update_message` replaces the text and keeps the message in place.**
+  Teams shows it as edited in the same bubble. This is the right answer to a
+  typo, a wrong time, a missing detail.
+- **`teams_delete_message` takes it back.** Right when the message should not
+  exist at all: wrong chat, wrong content, sent too early.
+
+Never correct by deleting and resending. The replacement arrives as a brand-new
+notification, everyone who already read the first message has to notice the gap,
+and the thread loses its order. Editing is the polite version.
+
+An edit sends the text only: mentions and attachments from the original are not
+re-created. That is deliberate — re-sending mention entities would ping people a
+second time for a message they were already notified about.
+
+## Chat membership
+
+`teams_chat_members` adds a person to a group chat or removes one. Adding
+someone hands them the conversation, so:
+
+- Resolve the person first (`teams_find_user`) when only a first name was given,
+  and say the full name in your reply. "Tom" is not an identity.
+- A **1:1** chat cannot be extended — Graph refuses. Use `teams_create_chat`
+  with everyone who belongs in it.
+- Removing someone needs an extra permission (`ChatMember.ReadWrite`); the tool
+  says so. Adding works with the default scopes.
+
+## Finding a time before booking one
+
+`teams_availability` reads **free/busy**, never calendars: "is Tuesday at two
+possible" is answerable, "what is Anna doing on Tuesday" is not, and must never
+be presented as if it were.
+
+1. Run it with everybody who has to be there and the length of the meeting.
+2. Offer the user two or three of the slots it returns — not all of them.
+3. Only once they pick one, book it with `teams_create_meeting`.
+
+Never book a slot because it looked free, and never dress the busy blocks up as
+anything more than times: knowing that somebody is busy is the point, knowing why
+is their business.
+
+## Answering an invitation
+
+`teams_respond_invite` accepts, declines or marks an invitation as tentative,
+and tells the organizer unless `sendResponse: false`. This fills the user's
+calendar and answers another person, so it needs their decision — "say yes to
+whatever looks relevant" is not one.
+
+A meeting the user **organizes** has no invitation to answer: change it with
+`teams_update_meeting`, cancel it with `teams_cancel_meeting`.
+
 ## Listen mode
 
 Listen mode is the only case where pi acts without being asked: it polls the

package/src/extension/index.ts

@@ -51,10 +51,13 @@ import {
 	teamsReplyChannelMessageTool,
 	teamsSendChannelMessageTool,
 } from "../tools/teams-send-channel-message.ts";
-import { teamsCreateChannelTool } from "../tools/teams-create-channel.ts";
 import { teamsListFilesTool } from "../tools/teams-list-files.ts";
 import { teamsSearchMessagesTool } from "../tools/teams-search-messages.ts";
 import { teamsReactTool } from "../tools/teams-react.ts";
+import { teamsMarkReadTool } from "../tools/teams-mark-read.ts";
+import { teamsUpdateMessageTool } from "../tools/teams-update-message.ts";
+import { teamsChatMembersTool } from "../tools/teams-chat-members.ts";
+import { teamsAvailabilityTool } from "../tools/teams-availability.ts";
 import { teamsDeleteMessageTool } from "../tools/teams-delete-message.ts";
 import { teamsInboxTool } from "../tools/teams-inbox.ts";
 import { teamsWatchTool } from "../tools/teams-watch.ts";
@@ -68,6 +71,7 @@ import {
 	teamsCreateMeetingTool,
 	teamsGetMeetingTool,
 	teamsListMeetingsTool,
+	teamsRespondInviteTool,
 	teamsUpdateMeetingTool,
 } from "../tools/teams-meetings.ts";
 
@@ -94,16 +98,18 @@ const tools = [
 	teamsReadChatTool,
 	teamsSendChatMessageTool,
 	teamsCreateChatTool,
+	teamsMarkReadTool,
+	teamsChatMembersTool,
 	// Channels
 	teamsReadChannelTool,
 	teamsReadThreadTool,
 	teamsSendChannelMessageTool,
 	teamsReplyChannelMessageTool,
-	teamsCreateChannelTool,
 	teamsListFilesTool,
 	// Cross-cutting
 	teamsSearchMessagesTool,
 	teamsReactTool,
+	teamsUpdateMessageTool,
 	teamsDeleteMessageTool,
 	teamsInboxTool,
 	// Presence
@@ -113,8 +119,10 @@ const tools = [
 	// Calendar
 	teamsListMeetingsTool,
 	teamsGetMeetingTool,
+	teamsAvailabilityTool,
 	teamsCreateMeetingTool,
 	teamsUpdateMeetingTool,
+	teamsRespondInviteTool,
 	teamsCancelMeetingTool,
 ];
 

package/src/graph/calendar.ts

@@ -143,6 +143,93 @@ export async function cancelEvent(
 	}
 }
 
+/** RSVP responses Graph accepts on an invitation. */
+export type EventResponse = "accept" | "decline" | "tentativelyAccept";
+
+/**
+ * Answer a meeting invitation.
+ *
+ * This is the calendar's equivalent of saying yes out loud: with
+ * `sendResponse` the organizer is notified, which is why the tool asks for
+ * confirmation rather than doing it quietly.
+ */
+export async function respondToEvent(
+	conn: TeamsConnection,
+	eventId: string,
+	response: EventResponse,
+	options: { comment?: string; sendResponse?: boolean; signal?: AbortSignal } = {},
+): Promise<void> {
+	await graphPost(
+		conn,
+		`/me/events/${encodeURIComponent(eventId)}/${response}`,
+		{ comment: options.comment, sendResponse: options.sendResponse !== false },
+		{ signal: options.signal },
+	);
+}
+
+// ---------------------------------------------------------------------------
+// Free / busy
+// ---------------------------------------------------------------------------
+
+/** One person's availability over the requested window. */
+export interface FreeBusyWindow {
+	/** The address Graph matched the schedule to */
+	scheduleId: string;
+	/**
+	 * One character per slot, starting at the window start:
+	 * `0` free, `1` tentative, `2` busy, `3` out of office, `4` working elsewhere.
+	 */
+	availabilityView: string;
+	/** Everything that was not free, with subject omitted on purpose */
+	busy: Array<{ status: string; start: string; end: string }>;
+}
+
+/**
+ * Free/busy for several people in one call.
+ *
+ * `getSchedule` is what a delegated token may read about another person's
+ * calendar — free/busy, not the appointments — and it is the reason
+ * availability works without the `.Shared` scopes that `findMeetingTimes`
+ * insists on. Subjects are reported by Graph but dropped here: knowing that
+ * somebody is busy is the point, knowing why is their business.
+ */
+export async function getSchedule(
+	conn: TeamsConnection,
+	input: {
+		schedules: string[];
+		start: string;
+		end: string;
+		timeZone: string;
+		/** Slot width in minutes; Graph allows 5–1440 */
+		intervalMinutes?: number;
+		signal?: AbortSignal;
+	},
+): Promise<FreeBusyWindow[]> {
+	const raw = await graphPost<Raw>(conn, "/me/calendar/getSchedule", {
+		schedules: input.schedules,
+		startTime: { dateTime: input.start, timeZone: input.timeZone },
+		endTime: { dateTime: input.end, timeZone: input.timeZone },
+		availabilityViewInterval: Math.min(Math.max(input.intervalMinutes ?? 30, 5), 1440),
+	}, {
+		signal: input.signal,
+		// Without this the busy blocks come back in UTC while the view is indexed
+		// in the requested zone, and the two would not line up.
+		headers: { Prefer: `outlook.timezone="${input.timeZone}"` },
+	});
+
+	return (raw?.value ?? []).map((entry: Raw) => ({
+		scheduleId: entry.scheduleId ?? "",
+		availabilityView: entry.availabilityView ?? "",
+		busy: (entry.scheduleItems ?? [])
+			.filter((item: Raw) => item.status && item.status !== "free")
+			.map((item: Raw) => ({
+				status: item.status,
+				start: item.start?.dateTime ?? "",
+				end: item.end?.dateTime ?? "",
+			})),
+	}));
+}
+
 /** Ad-hoc meeting link with no calendar entry. */
 export async function createOnlineMeeting(
 	conn: TeamsConnection,

package/src/graph/chats.ts

@@ -3,10 +3,10 @@
  */
 
 import type { TeamsConnection } from "../config/index.ts";
-import type { ChatSummary, PersonRef } from "../types.ts";
-import { graphGetOptional, graphList, graphPost } from "./client.ts";
+import type { ChatMemberSummary, ChatSummary, PersonRef } from "../types.ts";
+import { graphDelete, graphGetOptional, graphList, graphPost } from "./client.ts";
 import { GraphError } from "../utils/errors.ts";
-import { mapChat } from "./mappers.ts";
+import { mapChat, mapChatMember } from "./mappers.ts";
 import { resolveUserId } from "./me.ts";
 
 /**
@@ -140,6 +140,137 @@ export async function createChat(
 	return mapChat((raw ?? {}) as Record<string, never>);
 }
 
+// ---------------------------------------------------------------------------
+// Read state
+// ---------------------------------------------------------------------------
+
+/**
+ * Endpoint and body for the two read-cursor actions.
+ *
+ * Graph takes the user in the **body**, not in the URL: the delegated token
+ * says who is allowed to act, the body says whose read state changes. Kept as
+ * a pure function (like `deletePath`) because this is the part worth testing.
+ */
+export function readStateRequest(
+	chatId: string,
+	user: { id: string; tenantId?: string },
+	read: boolean,
+): { path: string; body: Record<string, unknown> } {
+	return {
+		path: `/chats/${encodeURIComponent(chatId)}/${
+			read ? "markChatReadForUser" : "markChatUnreadForUser"
+		}`,
+		// `tenantId` may be undefined; JSON.stringify drops it, and Graph accepts
+		// the id alone.
+		body: { user: { id: user.id, tenantId: user.tenantId } },
+	};
+}
+
+/**
+ * Mark a chat as read — or unread again — for the signed-in user.
+ *
+ * This is the only read-state a delegated token may move, and it moves the
+ * same cursor the app moves when you open a chat: it does not touch what
+ * anyone else sees, but read receipts (where the tenant has them on) do make
+ * the chat look seen. Channel messages have no equivalent action.
+ */
+export async function setChatReadState(
+	conn: TeamsConnection,
+	chatId: string,
+	user: { id: string; tenantId?: string },
+	read: boolean,
+	options: { signal?: AbortSignal } = {},
+): Promise<void> {
+	const { path, body } = readStateRequest(chatId, user, read);
+	await graphPost(conn, path, body, { signal: options.signal });
+}
+
+// ---------------------------------------------------------------------------
+// Membership
+// ---------------------------------------------------------------------------
+
+/**
+ * The members of a chat, with the membership id each one is removed by.
+ *
+ * Read raw rather than through `mapChat`, because a `ChatSummary` keeps only
+ * the people (what a label and the scope rules need) and drops the membership
+ * id that removing someone requires.
+ */
+export async function listChatMembers(
+	conn: TeamsConnection,
+	chatId: string,
+	options: { signal?: AbortSignal } = {},
+): Promise<ChatMemberSummary[]> {
+	const raw = await graphList<Record<string, never>>(
+		conn,
+		`/chats/${encodeURIComponent(chatId)}/members`,
+		{ max: 100, signal: options.signal },
+	);
+	return raw.map((entry) => mapChatMember(entry));
+}
+
+/**
+ * Add a person to an existing chat.
+ *
+ * Graph binds the member by user id or UPN; a 1:1 chat cannot be extended (the
+ * Teams client converts it to a group chat, Graph refuses), so callers should
+ * check the chat type first.
+ */
+export async function addChatMember(
+	conn: TeamsConnection,
+	chatId: string,
+	person: PersonRef,
+	options: { signal?: AbortSignal } = {},
+): Promise<void> {
+	const bind = person.id ?? person.upn ?? person.mail;
+	if (!bind) throw new Error(`Cannot add ${person.displayName}: no user id, UPN or e-mail address.`);
+
+	await graphPost(
+		conn,
+		`/chats/${encodeURIComponent(chatId)}/members`,
+		{
+			"@odata.type": "#microsoft.graph.aadUserConversationMember",
+			"user@odata.bind": `https://graph.microsoft.com/v1.0/users/${encodeURIComponent(bind)}`,
+			roles: [],
+		},
+		{ signal: options.signal },
+	);
+}
+
+/** Remove one membership. Graph takes the membership id, not the user id. */
+export async function removeChatMember(
+	conn: TeamsConnection,
+	chatId: string,
+	membershipId: string,
+	options: { signal?: AbortSignal } = {},
+): Promise<void> {
+	await graphDelete(
+		conn,
+		`/chats/${encodeURIComponent(chatId)}/members/${encodeURIComponent(membershipId)}`,
+		{ signal: options.signal },
+	);
+}
+
+/**
+ * Find the membership of one person in a chat.
+ *
+ * Matching goes through the identifiers a caller can actually have: object id,
+ * UPN, e-mail, display name.
+ */
+export function matchChatMember(
+	members: readonly ChatMemberSummary[],
+	reference: string,
+): ChatMemberSummary | undefined {
+	const needle = reference.trim().toLowerCase();
+	if (!needle) return undefined;
+
+	return members.find((member) =>
+		[member.userId, member.upn, member.mail, member.displayName]
+			.filter((value): value is string => !!value)
+			.some((value) => value.toLowerCase() === needle),
+	);
+}
+
 /** Resolve people references (UPN, e-mail, name) to PersonRefs. */
 export async function resolveParticipants(
 	conn: TeamsConnection,

package/src/graph/mappers.ts

@@ -9,6 +9,7 @@
 
 import type {
 	ChannelSummary,
+	ChatMemberSummary,
 	ChatSummary,
 	DriveItemSummary,
 	EventSummary,
@@ -67,6 +68,25 @@ export function mapMember(raw: Raw): MemberSummary {
 	};
 }
 
+/**
+ * A chat member.
+ *
+ * Graph exposes two identifiers per member and they are not interchangeable:
+ * the membership id is what removes someone, the user id is what says who they
+ * are. Keeping both here is cheaper than looking them up again later.
+ */
+export function mapChatMember(raw: Raw): ChatMemberSummary {
+	const user = raw.user ?? raw;
+	return {
+		membershipId: raw.id ?? "",
+		userId: user?.id ?? undefined,
+		displayName: raw.displayName ?? user?.displayName ?? "(unknown)",
+		upn: user?.userPrincipalName ?? raw.userPrincipalName ?? undefined,
+		mail: user?.email ?? raw.email ?? undefined,
+		roles: Array.isArray(raw.roles) ? raw.roles : [],
+	};
+}
+
 /** Identifiers a person can be matched against by the scope rules. */
 export function personCandidates(person: PersonRef | MemberSummary | undefined): (string | undefined)[] {
 	if (!person) return [];