@patimweb/pi-teams 1.0.0

package/src/graph/messages.ts

@@ -0,0 +1,383 @@
+/**
+ * Reading and writing messages — chats, channels, replies, reactions.
+ *
+ * This is the module that speaks in the user's name, so the shapes it builds
+ * are deliberately explicit: a mention is only sent when the caller resolved a
+ * real person for it, and an edit or delete always targets one message ID that
+ * the caller obtained from a read.
+ */
+
+import type { TeamsConnection } from "../config/index.ts";
+import type { ChannelSummary, MessageLocation, MessageSummary, PersonRef } from "../types.ts";
+import { graphGetOptional, graphList, graphPost } from "./client.ts";
+import { mapMessage } from "./mappers.ts";
+import { textToHtml } from "../utils/formatting.ts";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+type Raw = Record<string, any>;
+
+// ---------------------------------------------------------------------------
+// Message bodies
+// ---------------------------------------------------------------------------
+
+export interface MessageInput {
+	/** Message text — plain text unless `html` is true */
+	body: string;
+	/** Treat `body` as raw HTML instead of escaping it */
+	html?: boolean;
+	/** Channel messages only */
+	subject?: string;
+	/** "normal" | "high" | "urgent" */
+	importance?: string;
+	/** People to @-mention; each must appear in the body as @DisplayName */
+	mentions?: PersonRef[];
+}
+
+/**
+ * Build the Graph message body.
+ *
+ * Mentions are the fiddly part: Teams requires an `<at id="N">` span in the
+ * HTML *and* a matching entry in the `mentions` array. The display name is
+ * replaced in the text so the caller can just write "@Anna Schmidt".
+ */
+export function buildMessageBody(input: MessageInput): Record<string, unknown> {
+	const mentions = input.mentions ?? [];
+	let content = input.html ? input.body : textToHtml(input.body);
+
+	const mentionEntries: Record<string, unknown>[] = [];
+	mentions.forEach((person, index) => {
+		const tag = `<at id="${index}">${escapeHtml(person.displayName)}</at>`;
+		const needle = new RegExp(`@${escapeRegExp(person.displayName)}`, "g");
+		if (needle.test(content)) {
+			content = content.replace(needle, tag);
+		} else {
+			// Not referenced in the text — prepend it so the mention still fires.
+			content = `${tag} ${content}`;
+		}
+		mentionEntries.push({
+			id: index,
+			mentionText: person.displayName,
+			mentioned: {
+				user: {
+					displayName: person.displayName,
+					id: person.id,
+					userIdentityType: "aadUser",
+				},
+			},
+		});
+	});
+
+	const body: Record<string, unknown> = {
+		body: { contentType: "html", content },
+	};
+	if (input.subject) body.subject = input.subject;
+	if (input.importance) body.importance = input.importance;
+	if (mentionEntries.length > 0) body.mentions = mentionEntries;
+
+	return body;
+}
+
+function escapeHtml(value: string): string {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+function chatPath(chatId: string): string {
+	return `/chats/${encodeURIComponent(chatId)}/messages`;
+}
+
+function channelPath(teamId: string, channelId: string): string {
+	return `/teams/${encodeURIComponent(teamId)}/channels/${encodeURIComponent(channelId)}/messages`;
+}
+
+// ---------------------------------------------------------------------------
+// Reading — chats
+// ---------------------------------------------------------------------------
+
+export async function listChatMessages(
+	conn: TeamsConnection,
+	chatId: string,
+	options: { max?: number; signal?: AbortSignal } = {},
+): Promise<MessageSummary[]> {
+	const raw = await graphList<Raw>(conn, chatPath(chatId), {
+		query: { $top: Math.min(options.max ?? 25, 50) },
+		max: options.max ?? 25,
+		signal: options.signal,
+	});
+	const location: MessageLocation = { kind: "chat", chatId };
+	return raw.map((entry) => mapMessage(entry, location));
+}
+
+export async function getChatMessage(
+	conn: TeamsConnection,
+	chatId: string,
+	messageId: string,
+	signal?: AbortSignal,
+): Promise<MessageSummary | undefined> {
+	const raw = await graphGetOptional<Raw>(
+		conn,
+		`${chatPath(chatId)}/${encodeURIComponent(messageId)}`,
+		{ signal },
+	);
+	return raw ? mapMessage(raw, { kind: "chat", chatId }) : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Reading — channels
+// ---------------------------------------------------------------------------
+
+export async function listChannelMessages(
+	conn: TeamsConnection,
+	channel: ChannelSummary,
+	options: { max?: number; withReplies?: boolean; signal?: AbortSignal } = {},
+): Promise<MessageSummary[]> {
+	if (!channel.teamId) throw new Error("Channel is missing its teamId.");
+
+	const raw = await graphList<Raw>(conn, channelPath(channel.teamId, channel.id), {
+		query: { $top: Math.min(options.max ?? 25, 50) },
+		max: options.max ?? 25,
+		signal: options.signal,
+	});
+
+	const location: MessageLocation = {
+		kind: "channel",
+		teamId: channel.teamId,
+		teamName: channel.teamName,
+		channelId: channel.id,
+		channelName: channel.displayName,
+	};
+
+	const messages = raw.map((entry) => mapMessage(entry, location));
+
+	if (!options.withReplies) return messages;
+
+	// Threads are what a channel conversation actually is, so resolve them —
+	// sequentially, because a burst of parallel calls is the fastest way to get
+	// throttled by Graph.
+	for (const message of messages) {
+		const replies = await listChannelReplies(conn, channel, message.id, {
+			max: 20,
+			signal: options.signal,
+		});
+		message.replyCount = replies.length;
+	}
+	return messages;
+}
+
+export async function listChannelReplies(
+	conn: TeamsConnection,
+	channel: ChannelSummary,
+	messageId: string,
+	options: { max?: number; signal?: AbortSignal } = {},
+): Promise<MessageSummary[]> {
+	if (!channel.teamId) throw new Error("Channel is missing its teamId.");
+
+	const raw = await graphList<Raw>(
+		conn,
+		`${channelPath(channel.teamId, channel.id)}/${encodeURIComponent(messageId)}/replies`,
+		{
+			query: { $top: Math.min(options.max ?? 30, 50) },
+			max: options.max ?? 30,
+			signal: options.signal,
+		},
+	);
+
+	const location: MessageLocation = {
+		kind: "channel",
+		teamId: channel.teamId,
+		teamName: channel.teamName,
+		channelId: channel.id,
+		channelName: channel.displayName,
+	};
+	return raw.map((entry) => mapMessage(entry, location));
+}
+
+export async function getChannelMessage(
+	conn: TeamsConnection,
+	channel: ChannelSummary,
+	messageId: string,
+	signal?: AbortSignal,
+): Promise<MessageSummary | undefined> {
+	if (!channel.teamId) throw new Error("Channel is missing its teamId.");
+	const raw = await graphGetOptional<Raw>(
+		conn,
+		`${channelPath(channel.teamId, channel.id)}/${encodeURIComponent(messageId)}`,
+		{ signal },
+	);
+	return raw
+		? mapMessage(raw, {
+				kind: "channel",
+				teamId: channel.teamId,
+				teamName: channel.teamName,
+				channelId: channel.id,
+				channelName: channel.displayName,
+			})
+		: undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Writing
+// ---------------------------------------------------------------------------
+
+export async function sendChatMessage(
+	conn: TeamsConnection,
+	chatId: string,
+	input: MessageInput,
+	signal?: AbortSignal,
+): Promise<MessageSummary> {
+	const raw = await graphPost<Raw>(conn, chatPath(chatId), buildMessageBody(input), { signal });
+	return mapMessage(raw ?? {}, { kind: "chat", chatId });
+}
+
+export async function sendChannelMessage(
+	conn: TeamsConnection,
+	channel: ChannelSummary,
+	input: MessageInput,
+	signal?: AbortSignal,
+): Promise<MessageSummary> {
+	if (!channel.teamId) throw new Error("Channel is missing its teamId.");
+	const raw = await graphPost<Raw>(
+		conn,
+		channelPath(channel.teamId, channel.id),
+		buildMessageBody(input),
+		{ signal },
+	);
+	return mapMessage(raw ?? {}, {
+		kind: "channel",
+		teamId: channel.teamId,
+		teamName: channel.teamName,
+		channelId: channel.id,
+		channelName: channel.displayName,
+	});
+}
+
+export async function replyToChannelMessage(
+	conn: TeamsConnection,
+	channel: ChannelSummary,
+	messageId: string,
+	input: MessageInput,
+	signal?: AbortSignal,
+): Promise<MessageSummary> {
+	if (!channel.teamId) throw new Error("Channel is missing its teamId.");
+	const raw = await graphPost<Raw>(
+		conn,
+		`${channelPath(channel.teamId, channel.id)}/${encodeURIComponent(messageId)}/replies`,
+		buildMessageBody(input),
+		{ signal },
+	);
+	return mapMessage(raw ?? {}, {
+		kind: "channel",
+		teamId: channel.teamId,
+		teamName: channel.teamName,
+		channelId: channel.id,
+		channelName: channel.displayName,
+	});
+}
+
+/**
+ * Path for the softDelete / undoSoftDelete actions.
+ *
+ * The chat form takes an explicit user id — Graph does not accept `/me` here —
+ * which is why every caller has to resolve the signed-in user first.
+ */
+export function deletePath(
+	location: MessageLocation,
+	messageId: string,
+	userId: string,
+	replyId?: string,
+): string {
+	if (location.kind === "chat") {
+		return (
+			`/users/${encodeURIComponent(userId)}` +
+			`/chats/${encodeURIComponent(location.chatId!)}` +
+			`/messages/${encodeURIComponent(messageId)}`
+		);
+	}
+	const base = `${channelPath(location.teamId!, location.channelId!)}/${encodeURIComponent(messageId)}`;
+	return replyId ? `${base}/replies/${encodeURIComponent(replyId)}` : base;
+}
+
+/**
+ * Delete one of the signed-in user's own messages (soft delete, as in the app).
+ *
+ * Graph exposes this as an action, not an HTTP DELETE, and only for the sender.
+ */
+export async function softDeleteMessage(
+	conn: TeamsConnection,
+	location: MessageLocation,
+	messageId: string,
+	userId: string,
+	options: { replyId?: string; signal?: AbortSignal } = {},
+): Promise<void> {
+	await graphPost(
+		conn,
+		`${deletePath(location, messageId, userId, options.replyId)}/softDelete`,
+		undefined,
+		{ signal: options.signal },
+	);
+}
+
+/** Restore a message that was soft-deleted. */
+export async function undoSoftDeleteMessage(
+	conn: TeamsConnection,
+	location: MessageLocation,
+	messageId: string,
+	userId: string,
+	options: { replyId?: string; signal?: AbortSignal } = {},
+): Promise<void> {
+	await graphPost(
+		conn,
+		`${deletePath(location, messageId, userId, options.replyId)}/undoSoftDelete`,
+		undefined,
+		{ signal: options.signal },
+	);
+}
+
+// ---------------------------------------------------------------------------
+// Reactions
+// ---------------------------------------------------------------------------
+
+function reactionBase(location: MessageLocation, messageId: string, replyId?: string): string {
+	if (location.kind === "chat") {
+		return `/chats/${encodeURIComponent(location.chatId!)}/messages/${encodeURIComponent(messageId)}`;
+	}
+	const channelBase = `${channelPath(location.teamId!, location.channelId!)}/${encodeURIComponent(messageId)}`;
+	return replyId ? `${channelBase}/replies/${encodeURIComponent(replyId)}` : channelBase;
+}
+
+export async function setReaction(
+	conn: TeamsConnection,
+	location: MessageLocation,
+	messageId: string,
+	reactionType: string,
+	options: { replyId?: string; signal?: AbortSignal } = {},
+): Promise<void> {
+	await graphPost(
+		conn,
+		`${reactionBase(location, messageId, options.replyId)}/setReaction`,
+		{ reactionType },
+		{ signal: options.signal },
+	);
+}
+
+export async function unsetReaction(
+	conn: TeamsConnection,
+	location: MessageLocation,
+	messageId: string,
+	reactionType: string,
+	options: { replyId?: string; signal?: AbortSignal } = {},
+): Promise<void> {
+	await graphPost(
+		conn,
+		`${reactionBase(location, messageId, options.replyId)}/unsetReaction`,
+		{ reactionType },
+		{ signal: options.signal },
+	);
+}

package/src/graph/presence.ts

@@ -0,0 +1,160 @@
+/**
+ * Presence — reading who is available and setting the user's own status.
+ *
+ * Setting presence uses `setUserPreferredPresence`, not `setPresence`: the
+ * latter is tied to an application session and gets overwritten by the Teams
+ * client within seconds. Preferred presence is what the user themselves sets
+ * in the app, so it behaves the way they expect — including the expiry.
+ */
+
+import type { TeamsConnection } from "../config/index.ts";
+import type { PresenceInfo } from "../types.ts";
+import { graphList, graphPost, graphRequest } from "./client.ts";
+import { mapPresence } from "./mappers.ts";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+type Raw = Record<string, any>;
+
+/** Availability values Graph accepts for preferred presence. */
+export const AVAILABILITY_VALUES = [
+	"Available",
+	"Busy",
+	"DoNotDisturb",
+	"BeRightBack",
+	"Away",
+	"Offline",
+] as const;
+
+export type Availability = (typeof AVAILABILITY_VALUES)[number];
+
+/** Graph pairs each availability with a specific activity. */
+const ACTIVITY_FOR: Record<Availability, string> = {
+	Available: "Available",
+	Busy: "Busy",
+	DoNotDisturb: "DoNotDisturb",
+	BeRightBack: "BeRightBack",
+	Away: "Away",
+	Offline: "OffWork",
+};
+
+export function activityFor(availability: Availability): string {
+	return ACTIVITY_FOR[availability];
+}
+
+export async function getMyPresence(
+	conn: TeamsConnection,
+	signal?: AbortSignal,
+): Promise<PresenceInfo> {
+	const raw = await graphRequest<Raw>(conn, "GET", "/me/presence", { signal });
+	return mapPresence(raw ?? {}, "you");
+}
+
+export async function getPresenceForUser(
+	conn: TeamsConnection,
+	userId: string,
+	displayName?: string,
+	signal?: AbortSignal,
+): Promise<PresenceInfo> {
+	const raw = await graphRequest<Raw>(
+		conn,
+		"GET",
+		`/users/${encodeURIComponent(userId)}/presence`,
+		{ signal },
+	);
+	return mapPresence(raw ?? {}, displayName);
+}
+
+/**
+ * Presence for several people at once.
+ *
+ * Graph caps this action at 650 IDs per call; batching in 100s keeps request
+ * bodies small and the throttling risk low.
+ */
+export async function getPresenceForUsers(
+	conn: TeamsConnection,
+	userIds: string[],
+	names: Map<string, string>,
+	signal?: AbortSignal,
+): Promise<PresenceInfo[]> {
+	const results: PresenceInfo[] = [];
+
+	for (let i = 0; i < userIds.length; i += 100) {
+		const batch = userIds.slice(i, i + 100);
+		const response = await graphPost<Raw>(
+			conn,
+			"/communications/getPresencesByUserId",
+			{ ids: batch },
+			{ signal },
+		);
+		for (const entry of response?.value ?? []) {
+			results.push(mapPresence(entry, names.get(entry.id)));
+		}
+	}
+
+	return results;
+}
+
+/**
+ * Set the signed-in user's preferred presence.
+ *
+ * @param expirationDuration - ISO 8601 duration, e.g. "PT2H". Omit to let
+ * Microsoft apply its default (1 day for Busy/DoNotDisturb, 7 days otherwise).
+ */
+export async function setPreferredPresence(
+	conn: TeamsConnection,
+	availability: Availability,
+	options: { expirationDuration?: string; signal?: AbortSignal } = {},
+): Promise<void> {
+	const body: Record<string, unknown> = {
+		availability,
+		activity: activityFor(availability),
+	};
+	if (options.expirationDuration) body.expirationDuration = options.expirationDuration;
+
+	await graphPost(conn, "/me/presence/setUserPreferredPresence", body, { signal: options.signal });
+}
+
+/** Hand presence back to Teams' automatic calculation. */
+export async function clearPreferredPresence(
+	conn: TeamsConnection,
+	signal?: AbortSignal,
+): Promise<void> {
+	await graphPost(conn, "/me/presence/clearUserPreferredPresence", undefined, { signal });
+}
+
+/** Set or clear the status message shown under the user's name. */
+export async function setStatusMessage(
+	conn: TeamsConnection,
+	message: string,
+	options: { expiresAt?: string; signal?: AbortSignal } = {},
+): Promise<void> {
+	const statusMessage: Record<string, unknown> = {
+		message: { content: message, contentType: "text" },
+	};
+	if (options.expiresAt) {
+		statusMessage.expiryDateTime = { dateTime: options.expiresAt, timeZone: "UTC" };
+	}
+	await graphPost(conn, "/me/presence/setStatusMessage", { statusMessage }, { signal: options.signal });
+}
+
+/** Presence of everyone in a chat — handy before pinging a group. */
+export async function getChatPresence(
+	conn: TeamsConnection,
+	chatId: string,
+	signal?: AbortSignal,
+): Promise<PresenceInfo[]> {
+	const members = await graphList<Raw>(conn, `/chats/${encodeURIComponent(chatId)}/members`, {
+		max: 50,
+		signal,
+	});
+	const names = new Map<string, string>();
+	const ids: string[] = [];
+	for (const member of members) {
+		if (member.userId) {
+			ids.push(member.userId);
+			names.set(member.userId, member.displayName ?? "(unknown)");
+		}
+	}
+	if (ids.length === 0) return [];
+	return getPresenceForUsers(conn, ids, names, signal);
+}

package/src/graph/search.ts

@@ -0,0 +1,111 @@
+/**
+ * Message search across chats and channels.
+ *
+ * Uses the Microsoft Search API (`POST /search/query`, entityType
+ * `chatMessage`), which is the only endpoint that searches a user's whole
+ * Teams history in one call. Results come back as search hits with a summary
+ * and a partial resource, so they are normalized here into MessageSummary.
+ */
+
+import type { TeamsConnection } from "../config/index.ts";
+import type { MessageLocation, MessageSummary } from "../types.ts";
+import { graphPost } from "./client.ts";
+import { mapMessage } from "./mappers.ts";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+type Raw = Record<string, any>;
+
+export interface SearchHit {
+	message: MessageSummary;
+	/** Search summary with <c0> highlight markers stripped */
+	summary?: string;
+	/** Where the hit lives, when the resource carried enough information */
+	channelIdentity?: { teamId?: string; channelId?: string };
+	chatId?: string;
+}
+
+/**
+ * Search Teams messages.
+ *
+ * @param query - KQL-ish query string; plain words work, as do `from:` filters
+ * @param max - hits to return (Graph pages in blocks of 25)
+ */
+export async function searchMessages(
+	conn: TeamsConnection,
+	query: string,
+	options: { max?: number; from?: number; signal?: AbortSignal } = {},
+): Promise<SearchHit[]> {
+	const size = Math.min(options.max ?? 25, 25);
+
+	const response = await graphPost<Raw>(
+		conn,
+		"/search/query",
+		{
+			requests: [
+				{
+					entityTypes: ["chatMessage"],
+					query: { queryString: query },
+					from: options.from ?? 0,
+					size,
+				},
+			],
+		},
+		{ signal: options.signal },
+	);
+
+	const containers = response?.value?.[0]?.hitsContainers ?? [];
+	const hits: SearchHit[] = [];
+
+	for (const container of containers) {
+		for (const hit of container.hits ?? []) {
+			const resource = hit.resource ?? {};
+			const channelIdentity = resource.channelIdentity as
+				| { teamId?: string; channelId?: string }
+				| undefined;
+
+			const location: MessageLocation | undefined = channelIdentity?.channelId
+				? {
+						kind: "channel",
+						teamId: channelIdentity.teamId,
+						channelId: channelIdentity.channelId,
+					}
+				: resource.chatId
+					? { kind: "chat", chatId: resource.chatId }
+					: undefined;
+
+			hits.push({
+				message: mapMessage(resource, location),
+				summary: typeof hit.summary === "string"
+					? hit.summary.replace(/<\/?c\d+>/g, "").trim()
+					: undefined,
+				channelIdentity,
+				chatId: resource.chatId,
+			});
+		}
+	}
+
+	return hits.slice(0, options.max ?? 25);
+}
+
+/** Render search hits for the agent, keeping the IDs needed for follow-ups. */
+export function formatSearchHits(hits: readonly SearchHit[], query: string): string {
+	if (hits.length === 0) return `No Teams messages found for "${query}".`;
+
+	const lines = [`## Search: "${query}"`, "", `${hits.length} hit(s):`, ""];
+	for (const hit of hits) {
+		const who = hit.message.from?.displayName ?? "(unknown)";
+		const when = hit.message.createdDateTime
+			? new Date(hit.message.createdDateTime).toISOString().slice(0, 16).replace("T", " ")
+			: "";
+		const where = hit.channelIdentity?.channelId
+			? `channel ${hit.channelIdentity.channelId}`
+			: hit.chatId
+				? `chat ${hit.chatId}`
+				: "unknown location";
+
+		lines.push(`- **${who}**${when ? ` · ${when}` : ""} · ${where}`);
+		lines.push(`  ${hit.summary || hit.message.text.slice(0, 200)}`);
+		lines.push(`  messageId: ${hit.message.id}`);
+	}
+	return lines.join("\n");
+}