@patimweb/pi-teams 1.0.0

package/src/graph/calendar.ts

@@ -0,0 +1,165 @@
+/**
+ * Calendar and Teams meetings.
+ *
+ * Creating a meeting goes through a calendar event with `isOnlineMeeting:
+ * true` rather than `/me/onlineMeetings`: that way the meeting lands in
+ * everyone's calendar with invitations, which is what a person means when they
+ * say "set up a Teams meeting". `/me/onlineMeetings` is still exposed for the
+ * ad-hoc "just give me a join link" case.
+ */
+
+import type { TeamsConnection } from "../config/index.ts";
+import type { EventSummary, OnlineMeetingSummary } from "../types.ts";
+import { graphDelete, graphGetOptional, graphList, graphPatch, graphPost } from "./client.ts";
+import { mapEvent } from "./mappers.ts";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+type Raw = Record<string, any>;
+
+export interface EventInput {
+	subject: string;
+	/** ISO 8601 local date-time, e.g. "2026-09-15T10:00:00" */
+	start: string;
+	end: string;
+	/** IANA or Windows time zone name; defaults to the mailbox setting */
+	timeZone?: string;
+	/** SMTP addresses */
+	attendees?: string[];
+	/** Optional attendees */
+	optionalAttendees?: string[];
+	body?: string;
+	location?: string;
+	/** Create a Teams meeting link (default true) */
+	onlineMeeting?: boolean;
+}
+
+/** Events in a time range, ordered by start. */
+export async function listEvents(
+	conn: TeamsConnection,
+	options: { start?: string; end?: string; max?: number; signal?: AbortSignal } = {},
+): Promise<EventSummary[]> {
+	const start = options.start ?? new Date().toISOString();
+	const end = options.end ?? new Date(Date.now() + 7 * 24 * 3600 * 1000).toISOString();
+
+	// calendarView expands recurring series into real occurrences; /me/events
+	// would return the series master and miss today's instance.
+	const raw = await graphList<Raw>(conn, "/me/calendarView", {
+		query: {
+			startDateTime: start,
+			endDateTime: end,
+			$orderby: "start/dateTime",
+			$top: Math.min(options.max ?? 25, 50),
+			$select:
+				"id,subject,start,end,isAllDay,isOnlineMeeting,onlineMeeting,organizer,attendees,location,bodyPreview,webLink",
+		},
+		headers: { Prefer: 'outlook.timezone="UTC"' },
+		max: options.max ?? 25,
+		signal: options.signal,
+	});
+
+	return raw.map((entry) => mapEvent(entry));
+}
+
+export async function getEvent(
+	conn: TeamsConnection,
+	eventId: string,
+	signal?: AbortSignal,
+): Promise<EventSummary | undefined> {
+	const raw = await graphGetOptional<Raw>(conn, `/me/events/${encodeURIComponent(eventId)}`, {
+		signal,
+	});
+	return raw ? mapEvent(raw) : undefined;
+}
+
+function attendeeEntry(address: string, type: "required" | "optional") {
+	return { emailAddress: { address }, type };
+}
+
+export async function createEvent(
+	conn: TeamsConnection,
+	input: EventInput,
+	signal?: AbortSignal,
+): Promise<EventSummary> {
+	const timeZone = input.timeZone ?? "UTC";
+
+	const body: Record<string, unknown> = {
+		subject: input.subject,
+		start: { dateTime: input.start, timeZone },
+		end: { dateTime: input.end, timeZone },
+		isOnlineMeeting: input.onlineMeeting !== false,
+		onlineMeetingProvider: "teamsForBusiness",
+		attendees: [
+			...(input.attendees ?? []).map((a) => attendeeEntry(a, "required")),
+			...(input.optionalAttendees ?? []).map((a) => attendeeEntry(a, "optional")),
+		],
+	};
+	if (input.body) body.body = { contentType: "html", content: input.body };
+	if (input.location) body.location = { displayName: input.location };
+
+	const raw = await graphPost<Raw>(conn, "/me/events", body, { signal });
+	return mapEvent(raw ?? {});
+}
+
+export async function updateEvent(
+	conn: TeamsConnection,
+	eventId: string,
+	changes: Partial<EventInput>,
+	signal?: AbortSignal,
+): Promise<EventSummary> {
+	const timeZone = changes.timeZone ?? "UTC";
+	const body: Record<string, unknown> = {};
+
+	if (changes.subject) body.subject = changes.subject;
+	if (changes.start) body.start = { dateTime: changes.start, timeZone };
+	if (changes.end) body.end = { dateTime: changes.end, timeZone };
+	if (changes.body) body.body = { contentType: "html", content: changes.body };
+	if (changes.location) body.location = { displayName: changes.location };
+	if (changes.attendees || changes.optionalAttendees) {
+		body.attendees = [
+			...(changes.attendees ?? []).map((a) => attendeeEntry(a, "required")),
+			...(changes.optionalAttendees ?? []).map((a) => attendeeEntry(a, "optional")),
+		];
+	}
+
+	const raw = await graphPatch<Raw>(conn, `/me/events/${encodeURIComponent(eventId)}`, body, {
+		signal,
+	});
+	return mapEvent(raw ?? {});
+}
+
+/** Cancel an event you organize (sends cancellations), or decline/delete otherwise. */
+export async function cancelEvent(
+	conn: TeamsConnection,
+	eventId: string,
+	comment: string | undefined,
+	signal?: AbortSignal,
+): Promise<void> {
+	try {
+		await graphPost(conn, `/me/events/${encodeURIComponent(eventId)}/cancel`, { comment }, { signal });
+	} catch {
+		// Only the organizer may cancel; for everyone else removing it from the
+		// calendar is the closest equivalent.
+		await graphDelete(conn, `/me/events/${encodeURIComponent(eventId)}`, { signal });
+	}
+}
+
+/** Ad-hoc meeting link with no calendar entry. */
+export async function createOnlineMeeting(
+	conn: TeamsConnection,
+	input: { subject?: string; start?: string; end?: string },
+	signal?: AbortSignal,
+): Promise<OnlineMeetingSummary> {
+	const body: Record<string, unknown> = {};
+	if (input.subject) body.subject = input.subject;
+	if (input.start) body.startDateTime = input.start;
+	if (input.end) body.endDateTime = input.end;
+
+	const raw = await graphPost<Raw>(conn, "/me/onlineMeetings", body, { signal });
+	return {
+		id: raw?.id ?? "",
+		subject: raw?.subject ?? input.subject,
+		joinUrl: raw?.joinWebUrl ?? raw?.joinUrl ?? "",
+		start: raw?.startDateTime,
+		end: raw?.endDateTime,
+	};
+}

package/src/graph/chats.ts

@@ -0,0 +1,159 @@
+/**
+ * 1:1, group and meeting chats.
+ */
+
+import type { TeamsConnection } from "../config/index.ts";
+import type { ChatSummary, PersonRef } from "../types.ts";
+import { graphGetOptional, graphList, graphPost } from "./client.ts";
+import { GraphError } from "../utils/errors.ts";
+import { mapChat } from "./mappers.ts";
+import { resolveUserId } from "./me.ts";
+
+/**
+ * The signed-in user's chats, newest activity first.
+ *
+ * `$expand=members` is what turns an opaque `19:…@thread.v2` into "Anna Schmidt,
+ * Tom Weber", which is both what a person recognizes and what the scope rules
+ * match on — so it is always expanded, never optional.
+ */
+export async function listChats(
+	conn: TeamsConnection,
+	options: { max?: number; meId?: string; signal?: AbortSignal } = {},
+): Promise<ChatSummary[]> {
+	const max = options.max ?? 25;
+
+	const fetchChats = (orderBy: boolean) =>
+		graphList<Record<string, unknown>>(conn, "/me/chats", {
+			query: {
+				$expand: "members,lastMessagePreview",
+				$orderby: orderBy ? "lastMessagePreview/createdDateTime desc" : undefined,
+				$top: 50,
+			},
+			max,
+			signal: options.signal,
+		});
+
+	let raw: Record<string, unknown>[];
+	try {
+		raw = await fetchChats(true);
+	} catch (err) {
+		// $orderby combined with $expand is not accepted in every tenant. Losing
+		// the server-side sort is survivable; losing the chat list is not.
+		if (err instanceof GraphError && err.status === 400) {
+			raw = await fetchChats(false);
+		} else {
+			throw err;
+		}
+	}
+
+	const chats = raw.map((entry) => mapChat(entry as Record<string, never>, options.meId));
+
+	// Sort defensively: the fallback path is unsorted, and even the ordered one
+	// puts chats without a preview in an arbitrary place.
+	return chats.sort((a, b) => {
+		const left = a.lastUpdated ? new Date(a.lastUpdated).getTime() : 0;
+		const right = b.lastUpdated ? new Date(b.lastUpdated).getTime() : 0;
+		return right - left;
+	});
+}
+
+export async function getChat(
+	conn: TeamsConnection,
+	chatId: string,
+	options: { meId?: string; signal?: AbortSignal } = {},
+): Promise<ChatSummary | undefined> {
+	const raw = await graphGetOptional<Record<string, unknown>>(
+		conn,
+		`/chats/${encodeURIComponent(chatId)}`,
+		{ query: { $expand: "members" }, signal: options.signal },
+	);
+	return raw ? mapChat(raw as Record<string, never>, options.meId) : undefined;
+}
+
+/**
+ * Find an existing chat by label, topic or participant.
+ *
+ * Returns every match so the caller can refuse to act on an ambiguous one —
+ * "message Anna" must not land in the wrong Anna's chat.
+ */
+export async function findChats(
+	conn: TeamsConnection,
+	reference: string,
+	options: { max?: number; meId?: string; signal?: AbortSignal } = {},
+): Promise<ChatSummary[]> {
+	if (reference.startsWith("19:")) {
+		const direct = await getChat(conn, reference, options);
+		return direct ? [direct] : [];
+	}
+
+	const chats = await listChats(conn, { max: options.max ?? 100, meId: options.meId, signal: options.signal });
+	const lower = reference.toLowerCase();
+
+	const exact = chats.filter(
+		(chat) =>
+			chat.label.toLowerCase() === lower ||
+			chat.topic?.toLowerCase() === lower ||
+			chat.members.some(
+				(m) => m.upn?.toLowerCase() === lower || m.mail?.toLowerCase() === lower,
+			),
+	);
+	if (exact.length > 0) return exact;
+
+	return chats.filter(
+		(chat) =>
+			chat.label.toLowerCase().includes(lower) ||
+			chat.members.some((m) => m.displayName.toLowerCase().includes(lower)),
+	);
+}
+
+/**
+ * Create a 1:1 or group chat with the given people.
+ *
+ * Teams reuses the existing 1:1 chat when one is already there, so this is
+ * safe to call for "send Anna a message" without checking first.
+ */
+export async function createChat(
+	conn: TeamsConnection,
+	participants: PersonRef[],
+	options: { topic?: string; signal?: AbortSignal } = {},
+): Promise<ChatSummary> {
+	const chatType = participants.length > 1 ? "group" : "oneOnOne";
+
+	const members = [
+		// The signed-in user must be listed explicitly.
+		{
+			"@odata.type": "#microsoft.graph.aadUserConversationMember",
+			roles: ["owner"],
+			"user@odata.bind": "https://graph.microsoft.com/v1.0/me",
+		},
+		...participants.map((person) => ({
+			"@odata.type": "#microsoft.graph.aadUserConversationMember",
+			roles: ["owner"],
+			"user@odata.bind": `https://graph.microsoft.com/v1.0/users('${person.id ?? person.upn ?? person.mail}')`,
+		})),
+	];
+
+	const body: Record<string, unknown> = { chatType, members };
+	if (chatType === "group" && options.topic) body.topic = options.topic;
+
+	const raw = await graphPost<Record<string, unknown>>(conn, "/chats", body, { signal: options.signal });
+	return mapChat((raw ?? {}) as Record<string, never>);
+}
+
+/** Resolve people references (UPN, e-mail, name) to PersonRefs. */
+export async function resolveParticipants(
+	conn: TeamsConnection,
+	references: string[],
+	signal?: AbortSignal,
+): Promise<{ resolved: PersonRef[]; unresolved: string[] }> {
+	const resolved: PersonRef[] = [];
+	const unresolved: string[] = [];
+
+	for (const reference of references) {
+		const person = await resolveUserId(conn, reference, signal);
+		if (person) resolved.push(person);
+		else unresolved.push(reference);
+	}
+
+	return { resolved, unresolved };
+}

package/src/graph/client.ts

@@ -0,0 +1,234 @@
+/**
+ * Microsoft Graph HTTP client.
+ *
+ * A thin, dependency-free wrapper around fetch that handles the three things
+ * every Graph call needs and every hand-rolled call forgets: a fresh bearer
+ * token, `@odata.nextLink` paging, and 429/503 back-off honouring
+ * `Retry-After`.
+ */
+
+import type { TeamsConnection } from "../config/index.ts";
+import { getAccessToken } from "../auth/index.ts";
+import { GraphError } from "../utils/errors.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type HttpMethod = "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+
+export interface RequestOptions {
+	/** Query string parameters — `$select`, `$filter`, `$top`, … */
+	query?: Record<string, string | number | boolean | undefined>;
+	/** JSON request body */
+	body?: unknown;
+	signal?: AbortSignal;
+	/** Use the beta endpoint instead of v1.0 */
+	beta?: boolean;
+	/** Extra headers, e.g. Prefer: include-unknown-enum-members */
+	headers?: Record<string, string>;
+	/** Max retries for throttling responses (default 3) */
+	maxRetries?: number;
+}
+
+interface GraphErrorBody {
+	error?: {
+		code?: string;
+		message?: string;
+		innerError?: { "request-id"?: string; date?: string };
+	};
+}
+
+interface GraphCollection<T> {
+	value: T[];
+	"@odata.nextLink"?: string;
+	"@odata.count"?: number;
+}
+
+// ---------------------------------------------------------------------------
+// URL building
+// ---------------------------------------------------------------------------
+
+function buildUrl(conn: TeamsConnection, path: string, options: RequestOptions): string {
+	const base = options.beta
+		? conn.graphBaseUrl.replace(/\/v1\.0$/, "/beta")
+		: conn.graphBaseUrl;
+	const url = new URL(path.startsWith("http") ? path : `${base}${path.startsWith("/") ? "" : "/"}${path}`);
+
+	for (const [key, value] of Object.entries(options.query ?? {})) {
+		if (value === undefined) continue;
+		url.searchParams.set(key, String(value));
+	}
+
+	return url.toString();
+}
+
+// ---------------------------------------------------------------------------
+// Core request
+// ---------------------------------------------------------------------------
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Perform a Graph request and return the parsed body.
+ *
+ * Returns `undefined` for 204 No Content, which Graph uses for most writes
+ * (reactions, deletes, presence).
+ *
+ * @throws {GraphError} for any non-2xx response that survives the retries
+ */
+export async function graphRequest<T = unknown>(
+	conn: TeamsConnection,
+	method: HttpMethod,
+	path: string,
+	options: RequestOptions = {},
+): Promise<T | undefined> {
+	const maxRetries = options.maxRetries ?? 3;
+	const url = buildUrl(conn, path, options);
+
+	let attempt = 0;
+	for (;;) {
+		const token = await getAccessToken(conn, options.signal);
+
+		const headers: Record<string, string> = {
+			Authorization: `Bearer ${token.accessToken}`,
+			Accept: "application/json",
+			...options.headers,
+		};
+		if (options.body !== undefined) headers["Content-Type"] = "application/json";
+
+		const response = await fetch(url, {
+			method,
+			headers,
+			body: options.body === undefined ? undefined : JSON.stringify(options.body),
+			signal: options.signal,
+		});
+
+		if (response.status === 204 || response.status === 202) {
+			return undefined;
+		}
+
+		if (response.ok) {
+			const text = await response.text();
+			if (!text) return undefined;
+			return JSON.parse(text) as T;
+		}
+
+		// Throttling and transient service errors: back off and retry.
+		if ((response.status === 429 || response.status === 503) && attempt < maxRetries) {
+			const retryAfter = Number(response.headers.get("Retry-After") ?? "0");
+			// Exponential fallback when the header is missing, capped so a tool
+			// call cannot hang for minutes.
+			const waitMs = retryAfter > 0 ? retryAfter * 1000 : Math.min(2 ** attempt * 1000, 8000);
+			attempt += 1;
+			await sleep(waitMs);
+			continue;
+		}
+
+		throw await toGraphError(response);
+	}
+}
+
+async function toGraphError(response: Response): Promise<GraphError> {
+	let code = `HTTP${response.status}`;
+	let message = response.statusText || `Request failed with status ${response.status}`;
+	let requestId: string | undefined;
+	let raw: unknown;
+
+	try {
+		const text = await response.text();
+		if (text) {
+			raw = JSON.parse(text) as GraphErrorBody;
+			const body = raw as GraphErrorBody;
+			if (body.error?.code) code = body.error.code;
+			if (body.error?.message) message = body.error.message;
+			requestId = body.error?.innerError?.["request-id"];
+		}
+	} catch {
+		/* keep the status-based defaults */
+	}
+
+	return new GraphError(response.status, code, message, requestId, raw);
+}
+
+// ---------------------------------------------------------------------------
+// Collections
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch a collection, following `@odata.nextLink` until `max` items are
+ * collected. `max` exists because a chat history can be tens of thousands of
+ * messages and nobody wants that in a tool result.
+ */
+export async function graphList<T>(
+	conn: TeamsConnection,
+	path: string,
+	options: RequestOptions & { max?: number } = {},
+): Promise<T[]> {
+	const max = options.max ?? 100;
+	const items: T[] = [];
+	let nextPath: string | undefined = path;
+	let query: RequestOptions["query"] | undefined = options.query;
+
+	while (nextPath && items.length < max) {
+		const page: GraphCollection<T> | undefined = await graphRequest<GraphCollection<T>>(
+			conn,
+			"GET",
+			nextPath,
+			{ ...options, query },
+		);
+		if (!page?.value) break;
+
+		items.push(...page.value);
+		nextPath = page["@odata.nextLink"];
+		// nextLink already carries the query string.
+		query = undefined;
+	}
+
+	return items.slice(0, max);
+}
+
+/** GET a single resource; `undefined` on 404 instead of throwing. */
+export async function graphGetOptional<T>(
+	conn: TeamsConnection,
+	path: string,
+	options: RequestOptions = {},
+): Promise<T | undefined> {
+	try {
+		return await graphRequest<T>(conn, "GET", path, options);
+	} catch (err) {
+		if (err instanceof GraphError && err.status === 404) return undefined;
+		throw err;
+	}
+}
+
+/** POST a JSON body. */
+export function graphPost<T = unknown>(
+	conn: TeamsConnection,
+	path: string,
+	body: unknown,
+	options: RequestOptions = {},
+): Promise<T | undefined> {
+	return graphRequest<T>(conn, "POST", path, { ...options, body });
+}
+
+/** PATCH a JSON body. */
+export function graphPatch<T = unknown>(
+	conn: TeamsConnection,
+	path: string,
+	body: unknown,
+	options: RequestOptions = {},
+): Promise<T | undefined> {
+	return graphRequest<T>(conn, "PATCH", path, { ...options, body });
+}
+
+/** DELETE a resource. */
+export function graphDelete(
+	conn: TeamsConnection,
+	path: string,
+	options: RequestOptions = {},
+): Promise<unknown> {
+	return graphRequest(conn, "DELETE", path, options);
+}