@kodelyth/msteams 2026.5.39 → 2026.5.42

package/src/graph.ts

@@ -0,0 +1,308 @@
+import { readProviderJsonResponse } from "klaw/plugin-sdk/provider-http";
+import { fetchWithSsrFGuard, type MSTeamsConfig } from "../runtime-api.js";
+import { GRAPH_ROOT } from "./attachments/shared.js";
+
+const GRAPH_BETA = "https://graph.microsoft.com/beta";
+const NULL_BODY_STATUSES = new Set([101, 204, 205, 304]);
+import { createMSTeamsTokenProvider, loadMSTeamsSdkWithAuth } from "./sdk.js";
+import { readAccessToken } from "./token-response.js";
+import { resolveDelegatedAccessToken, resolveMSTeamsCredentials } from "./token.js";
+import { buildUserAgent } from "./user-agent.js";
+
+export type GraphUser = {
+  id?: string;
+  displayName?: string;
+  userPrincipalName?: string;
+  mail?: string;
+};
+
+type GraphGroup = {
+  id?: string;
+  displayName?: string;
+};
+
+type GraphChannel = {
+  id?: string;
+  displayName?: string;
+};
+
+export type GraphResponse<T> = { value?: T[] };
+
+export function normalizeQuery(value?: string | null): string {
+  return value?.trim() ?? "";
+}
+
+export function escapeOData(value: string): string {
+  return value.replace(/'/g, "''");
+}
+
+async function requestGraph(params: {
+  token: string;
+  path: string;
+  method?: "GET" | "POST" | "PATCH" | "DELETE";
+  root?: string;
+  headers?: Record<string, string>;
+  body?: unknown;
+  errorPrefix?: string;
+}): Promise<Response> {
+  const hasBody = params.body !== undefined;
+  const url = `${params.root ?? GRAPH_ROOT}${params.path}`;
+  const currentFetch = globalThis.fetch;
+  const { response, release } = await fetchWithSsrFGuard({
+    url,
+    fetchImpl: async (input, guardedInit) => await currentFetch(input, guardedInit),
+    init: {
+      method: params.method,
+      headers: {
+        "User-Agent": buildUserAgent(),
+        Authorization: `Bearer ${params.token}`,
+        ...(hasBody ? { "Content-Type": "application/json" } : {}),
+        ...params.headers,
+      },
+      body: hasBody ? JSON.stringify(params.body) : undefined,
+    },
+    auditContext: "msteams.graph",
+  });
+  try {
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new Error(
+        `${params.errorPrefix ?? "Graph"} ${params.path} failed (${response.status}): ${text || "unknown error"}`,
+      );
+    }
+    const body = NULL_BODY_STATUSES.has(response.status) ? null : await response.arrayBuffer();
+    return new Response(body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: new Headers(response.headers),
+    });
+  } finally {
+    await release();
+  }
+}
+
+async function readOptionalGraphJson<T>(res: Response, label: string): Promise<T> {
+  // Use optional chaining to stay resilient to partial test mocks that do not
+  // provide a status or Headers instance (they only shim `ok` + `json()`).
+  if (res.status === 204 || res.headers?.get?.("content-length") === "0") {
+    return undefined as T;
+  }
+  return await readProviderJsonResponse<T>(res, label);
+}
+
+export async function fetchGraphJson<T>(params: {
+  token: string;
+  path: string;
+  headers?: Record<string, string>;
+  /** HTTP method; defaults to "GET" */
+  method?: string;
+  /** Request body (serialized as JSON). Only used for non-GET methods. */
+  body?: unknown;
+}): Promise<T> {
+  const res = await requestGraph({
+    token: params.token,
+    path: params.path,
+    method: params.method as "GET" | "POST" | "DELETE" | undefined,
+    body: params.body,
+    headers: params.headers,
+  });
+  return await readOptionalGraphJson<T>(res, `Graph ${params.path} failed`);
+}
+
+/**
+ * Fetch JSON from an absolute Graph API URL (for example @odata.nextLink
+ * pagination URLs) without prepending GRAPH_ROOT.
+ */
+export async function fetchGraphAbsoluteUrl<T>(params: {
+  token: string;
+  url: string;
+  headers?: Record<string, string>;
+}): Promise<T> {
+  const { response, release } = await fetchWithSsrFGuard({
+    url: params.url,
+    init: {
+      headers: {
+        "User-Agent": buildUserAgent(),
+        Authorization: `Bearer ${params.token}`,
+        ...params.headers,
+      },
+    },
+    auditContext: "msteams.graph.absolute",
+  });
+  try {
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new Error(
+        `Graph ${params.url} failed (${response.status}): ${text || "unknown error"}`,
+      );
+    }
+    return await readProviderJsonResponse<T>(response, `Graph ${params.url} failed`);
+  } finally {
+    await release();
+  }
+}
+
+/** Graph collection response with optional pagination link. */
+type GraphPagedResponse<T> = {
+  value?: T[];
+  "@odata.nextLink"?: string;
+};
+
+/** Result of a paginated Graph API fetch. */
+type PaginatedResult<T> = {
+  items: T[];
+  truncated: boolean;
+  found?: T;
+};
+
+/**
+ * Fetch all pages of a Graph API collection, following @odata.nextLink.
+ * Optionally stop early when `findOne` matches an item.
+ */
+export async function fetchAllGraphPages<T>(params: {
+  token: string;
+  path: string;
+  headers?: Record<string, string>;
+  /** Max pages to fetch before stopping. Default: 50. */
+  maxPages?: number;
+  /** Stop pagination early when this predicate returns true. */
+  findOne?: (item: T) => boolean;
+}): Promise<PaginatedResult<T>> {
+  const maxPages = params.maxPages ?? 50;
+  const items: T[] = [];
+  let nextPath: string | undefined = params.path;
+
+  for (let page = 0; page < maxPages && nextPath; page++) {
+    const res: GraphPagedResponse<T> = await fetchGraphJson<GraphPagedResponse<T>>({
+      token: params.token,
+      path: nextPath,
+      headers: params.headers,
+    });
+
+    const pageItems = res.value ?? [];
+
+    if (params.findOne) {
+      const match = pageItems.find(params.findOne);
+      if (match) {
+        items.push(...pageItems);
+        return { items, truncated: false, found: match };
+      }
+    }
+
+    items.push(...pageItems);
+
+    // @odata.nextLink is an absolute URL; strip the Graph root to get a relative path
+    const rawNext: string | undefined = res["@odata.nextLink"];
+    if (rawNext) {
+      nextPath = rawNext
+        .replace("https://graph.microsoft.com/v1.0", "")
+        .replace("https://graph.microsoft.com/beta", "");
+    } else {
+      nextPath = undefined;
+    }
+  }
+
+  return { items, truncated: Boolean(nextPath) };
+}
+
+export async function resolveGraphToken(
+  cfg: unknown,
+  options?: { preferDelegated?: boolean },
+): Promise<string> {
+  const msteamsCfg = (cfg as { channels?: { msteams?: MSTeamsConfig } })?.channels?.msteams;
+  const creds = resolveMSTeamsCredentials(msteamsCfg);
+  if (!creds) {
+    throw new Error("MS Teams credentials missing");
+  }
+
+  // Try delegated token if requested and configured
+  if (options?.preferDelegated && msteamsCfg?.delegatedAuth?.enabled && creds.type === "secret") {
+    const delegated = await resolveDelegatedAccessToken({
+      tenantId: creds.tenantId,
+      clientId: creds.appId,
+      clientSecret: creds.appPassword,
+    });
+    if (delegated) {
+      return delegated;
+    }
+    // Fall through to app-only token
+  }
+
+  const { app } = await loadMSTeamsSdkWithAuth(creds);
+  const tokenProvider = createMSTeamsTokenProvider(app);
+  const graphTokenValue = await tokenProvider.getAccessToken("https://graph.microsoft.com");
+  const accessToken = readAccessToken(graphTokenValue);
+  if (!accessToken) {
+    throw new Error("MS Teams graph token unavailable");
+  }
+  return accessToken;
+}
+
+export async function listTeamsByName(token: string, query: string): Promise<GraphGroup[]> {
+  const escaped = escapeOData(query);
+  const filter = `resourceProvisioningOptions/Any(x:x eq 'Team') and startsWith(displayName,'${escaped}')`;
+  const path = `/groups?$filter=${encodeURIComponent(filter)}&$select=id,displayName`;
+  const { items } = await fetchAllGraphPages<GraphGroup>({ token, path, maxPages: 5 });
+  return items;
+}
+
+export async function postGraphJson<T>(params: {
+  token: string;
+  path: string;
+  body?: unknown;
+}): Promise<T> {
+  const res = await requestGraph({
+    token: params.token,
+    path: params.path,
+    method: "POST",
+    body: params.body,
+    errorPrefix: "Graph POST",
+  });
+  return readOptionalGraphJson<T>(res, `Graph POST ${params.path} failed`);
+}
+
+export async function postGraphBetaJson<T>(params: {
+  token: string;
+  path: string;
+  body?: unknown;
+}): Promise<T> {
+  const res = await requestGraph({
+    token: params.token,
+    path: params.path,
+    method: "POST",
+    root: GRAPH_BETA,
+    body: params.body,
+    errorPrefix: "Graph beta POST",
+  });
+  return readOptionalGraphJson<T>(res, `Graph beta POST ${params.path} failed`);
+}
+
+export async function deleteGraphRequest(params: { token: string; path: string }): Promise<void> {
+  await requestGraph({
+    token: params.token,
+    path: params.path,
+    method: "DELETE",
+    errorPrefix: "Graph DELETE",
+  });
+}
+
+export async function patchGraphJson<T>(params: {
+  token: string;
+  path: string;
+  body?: unknown;
+}): Promise<T> {
+  const res = await requestGraph({
+    token: params.token,
+    path: params.path,
+    method: "PATCH",
+    body: params.body,
+    errorPrefix: "Graph PATCH",
+  });
+  return readOptionalGraphJson<T>(res, `Graph PATCH ${params.path} failed`);
+}
+
+export async function listChannelsForTeam(token: string, teamId: string): Promise<GraphChannel[]> {
+  const path = `/teams/${encodeURIComponent(teamId)}/channels?$select=id,displayName`;
+  const { items } = await fetchAllGraphPages<GraphChannel>({ token, path, maxPages: 10 });
+  return items;
+}

package/src/inbound.test.ts

@@ -0,0 +1,221 @@
+import { describe, expect, it } from "vitest";
+import {
+  decodeHtmlEntities,
+  extractMSTeamsQuoteInfo,
+  htmlToPlainText,
+  normalizeMSTeamsConversationId,
+  parseMSTeamsActivityTimestamp,
+  stripMSTeamsMentionTags,
+  wasMSTeamsBotMentioned,
+} from "./inbound.js";
+
+describe("msteams inbound", () => {
+  describe("stripMSTeamsMentionTags", () => {
+    it("removes <at>...</at> tags and trims", () => {
+      expect(stripMSTeamsMentionTags("<at>Bot</at> hi")).toBe("hi");
+      expect(stripMSTeamsMentionTags("hi <at>Bot</at>")).toBe("hi");
+    });
+
+    it("removes <at ...> tags with attributes", () => {
+      expect(stripMSTeamsMentionTags('<at id="1">Bot</at> hi')).toBe("hi");
+      expect(stripMSTeamsMentionTags('hi <at itemid="2">Bot</at>')).toBe("hi");
+    });
+  });
+
+  describe("normalizeMSTeamsConversationId", () => {
+    it("strips the ;messageid suffix", () => {
+      expect(normalizeMSTeamsConversationId("19:abc@thread.tacv2;messageid=deadbeef")).toBe(
+        "19:abc@thread.tacv2",
+      );
+    });
+  });
+
+  describe("parseMSTeamsActivityTimestamp", () => {
+    it("returns undefined for empty/invalid values", () => {
+      expect(parseMSTeamsActivityTimestamp(undefined)).toBeUndefined();
+      expect(parseMSTeamsActivityTimestamp("not-a-date")).toBeUndefined();
+    });
+
+    it("parses string timestamps", () => {
+      const ts = parseMSTeamsActivityTimestamp("2024-01-01T00:00:00.000Z");
+      if (!ts) {
+        throw new Error("expected MSTeams timestamp parser to return a Date");
+      }
+      expect(ts.toISOString()).toBe("2024-01-01T00:00:00.000Z");
+    });
+
+    it("passes through Date instances", () => {
+      const d = new Date("2024-01-01T00:00:00.000Z");
+      expect(parseMSTeamsActivityTimestamp(d)).toBe(d);
+    });
+  });
+
+  describe("wasMSTeamsBotMentioned", () => {
+    it("returns true when a mention entity matches recipient.id", () => {
+      expect(
+        wasMSTeamsBotMentioned({
+          recipient: { id: "bot" },
+          entities: [{ type: "mention", mentioned: { id: "bot" } }],
+        }),
+      ).toBe(true);
+    });
+
+    it("returns false when there is no matching mention", () => {
+      expect(
+        wasMSTeamsBotMentioned({
+          recipient: { id: "bot" },
+          entities: [{ type: "mention", mentioned: { id: "other" } }],
+        }),
+      ).toBe(false);
+    });
+  });
+
+  describe("decodeHtmlEntities", () => {
+    it("decodes common entities", () => {
+      expect(decodeHtmlEntities("&amp;&lt;&gt;&quot;&#39;&#x27;&nbsp;")).toBe("&<>\"'' ");
+    });
+
+    it("leaves plain text unchanged", () => {
+      expect(decodeHtmlEntities("hello world")).toBe("hello world");
+    });
+
+    it("prevents double-decoding: &amp;lt; should become &lt; not <", () => {
+      // If &amp; were decoded first, &amp;lt; → &lt; → < (wrong).
+      // With &amp; decoded last, &amp;lt; stays as &lt; (correct).
+      expect(decodeHtmlEntities("&amp;lt;b&amp;gt;")).toBe("&lt;b&gt;");
+    });
+  });
+
+  describe("htmlToPlainText", () => {
+    it("strips tags and decodes entities", () => {
+      expect(htmlToPlainText("<strong>Hello &amp; world</strong>")).toBe("Hello & world");
+    });
+
+    it("collapses whitespace from tag removal", () => {
+      expect(htmlToPlainText("<p>foo</p><p>bar</p>")).toBe("foo bar");
+    });
+
+    it("trims leading and trailing whitespace", () => {
+      expect(htmlToPlainText("  <span>hi</span>  ")).toBe("hi");
+    });
+  });
+
+  describe("extractMSTeamsQuoteInfo", () => {
+    const replyAttachment = (overrides?: { content?: string; contentType?: string }) => ({
+      contentType: overrides?.contentType ?? "text/html",
+      content:
+        overrides?.content ??
+        '<blockquote itemtype="http://schema.skype.com/Reply" itemscope>' +
+          '<strong itemprop="mri">Alice</strong>' +
+          '<p itemprop="copy">Hello world</p>' +
+          "</blockquote>",
+    });
+
+    it("extracts sender and body from a Teams reply attachment", () => {
+      const result = extractMSTeamsQuoteInfo([replyAttachment()]);
+      expect(result).toEqual({ sender: "Alice", body: "Hello world" });
+    });
+
+    it("returns undefined for empty attachments array", () => {
+      expect(extractMSTeamsQuoteInfo([])).toBeUndefined();
+    });
+
+    it("returns undefined when no reply blockquote is present", () => {
+      expect(
+        extractMSTeamsQuoteInfo([{ contentType: "text/html", content: "<p>just a message</p>" }]),
+      ).toBeUndefined();
+    });
+
+    it("uses 'unknown' as sender when sender element is absent", () => {
+      const result = extractMSTeamsQuoteInfo([
+        {
+          contentType: "text/html",
+          content:
+            '<blockquote itemtype="http://schema.skype.com/Reply" itemscope>' +
+            '<p itemprop="copy">quoted text</p>' +
+            "</blockquote>",
+        },
+      ]);
+      expect(result).toEqual({ sender: "unknown", body: "quoted text" });
+    });
+
+    it("returns undefined when body element is absent", () => {
+      const result = extractMSTeamsQuoteInfo([
+        {
+          contentType: "text/html",
+          content:
+            '<blockquote itemtype="http://schema.skype.com/Reply" itemscope>' +
+            '<strong itemprop="mri">Alice</strong>' +
+            "</blockquote>",
+        },
+      ]);
+      expect(result).toBeUndefined();
+    });
+
+    it("decodes HTML entities in body text", () => {
+      const result = extractMSTeamsQuoteInfo([
+        {
+          contentType: "text/html",
+          content:
+            '<blockquote itemtype="http://schema.skype.com/Reply" itemscope>' +
+            '<strong itemprop="mri">Bob</strong>' +
+            '<p itemprop="copy">2 &lt; 3 &amp; 4 &gt; 1</p>' +
+            "</blockquote>",
+        },
+      ]);
+      expect(result).toEqual({ sender: "Bob", body: "2 < 3 & 4 > 1" });
+    });
+
+    it("handles multiline body by collapsing whitespace", () => {
+      const result = extractMSTeamsQuoteInfo([
+        {
+          contentType: "text/html",
+          content:
+            '<blockquote itemtype="http://schema.skype.com/Reply" itemscope>' +
+            '<strong itemprop="mri">Carol</strong>' +
+            '<p itemprop="copy">line one\nline two</p>' +
+            "</blockquote>",
+        },
+      ]);
+      expect(result?.body).toBe("line one line two");
+    });
+
+    it("skips non-string content values", () => {
+      expect(
+        extractMSTeamsQuoteInfo([{ contentType: "application/json", content: { foo: "bar" } }]),
+      ).toBeUndefined();
+    });
+
+    it("handles object content with .text property containing the reply HTML", () => {
+      const htmlContent =
+        '<blockquote itemtype="http://schema.skype.com/Reply" itemscope>' +
+        '<strong itemprop="mri">Dave</strong>' +
+        '<p itemprop="copy">hello from object</p>' +
+        "</blockquote>";
+      const result = extractMSTeamsQuoteInfo([
+        { contentType: "text/html", content: { text: htmlContent } },
+      ]);
+      expect(result).toEqual({ sender: "Dave", body: "hello from object" });
+    });
+
+    it("handles object content with .body property containing the reply HTML", () => {
+      const htmlContent =
+        '<blockquote itemtype="http://schema.skype.com/Reply" itemscope>' +
+        '<strong itemprop="mri">Eve</strong>' +
+        '<p itemprop="copy">hello from body field</p>' +
+        "</blockquote>";
+      const result = extractMSTeamsQuoteInfo([
+        { contentType: "text/html", content: { body: htmlContent } },
+      ]);
+      expect(result).toEqual({ sender: "Eve", body: "hello from body field" });
+    });
+
+    it("finds quote in second attachment when first has no quote", () => {
+      const result = extractMSTeamsQuoteInfo([
+        { contentType: "text/plain", content: "plain text" },
+        replyAttachment(),
+      ]);
+      expect(result).toEqual({ sender: "Alice", body: "Hello world" });
+    });
+  });
+});

package/src/inbound.ts

@@ -0,0 +1,148 @@
+type MSTeamsQuoteInfo = {
+  sender: string;
+  body: string;
+};
+
+/**
+ * Decode common HTML entities to plain text.
+ */
+export function decodeHtmlEntities(html: string): string {
+  return html
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&#x27;/g, "'")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&"); // must be last to prevent double-decoding (e.g. &amp;lt; → &lt; not <)
+}
+
+/**
+ * Strip HTML tags, preserving text content.
+ */
+export function htmlToPlainText(html: string): string {
+  return decodeHtmlEntities(
+    html
+      .replace(/<[^>]*>/g, " ")
+      .replace(/\s+/g, " ")
+      .trim(),
+  );
+}
+
+/**
+ * Extract quote info from MS Teams HTML reply attachments.
+ * Teams wraps quoted content in a blockquote with itemtype="http://schema.skype.com/Reply".
+ */
+export function extractMSTeamsQuoteInfo(
+  attachments: Array<{ contentType?: string | null; content?: unknown }>,
+): MSTeamsQuoteInfo | undefined {
+  for (const att of attachments) {
+    // Content may be a plain string or an object with .text/.body (e.g. Adaptive Card payloads).
+    let content = "";
+    if (typeof att.content === "string") {
+      content = att.content;
+    } else if (typeof att.content === "object" && att.content !== null) {
+      const record = att.content as Record<string, unknown>;
+      content =
+        typeof record.text === "string"
+          ? record.text
+          : typeof record.body === "string"
+            ? record.body
+            : "";
+    }
+    if (!content) {
+      continue;
+    }
+
+    // Look for the Skype Reply schema blockquote.
+    if (!content.includes("http://schema.skype.com/Reply")) {
+      continue;
+    }
+
+    // Extract sender from <strong itemprop="mri">.
+    const senderMatch = /<strong[^>]*itemprop=["']mri["'][^>]*>(.*?)<\/strong>/i.exec(content);
+    const sender = senderMatch?.[1] ? htmlToPlainText(senderMatch[1]) : undefined;
+
+    // Extract body from <p itemprop="copy">.
+    const bodyMatch = /<p[^>]*itemprop=["']copy["'][^>]*>(.*?)<\/p>/is.exec(content);
+    const body = bodyMatch?.[1] ? htmlToPlainText(bodyMatch[1]) : undefined;
+
+    if (body) {
+      return { sender: sender ?? "unknown", body };
+    }
+  }
+  return undefined;
+}
+
+type MentionableActivity = {
+  recipient?: { id?: string } | null;
+  entities?: Array<{
+    type?: string;
+    mentioned?: { id?: string };
+  }> | null;
+};
+
+export function normalizeMSTeamsConversationId(raw: string): string {
+  return raw.split(";")[0] ?? raw;
+}
+
+export function extractMSTeamsConversationMessageId(raw: string): string | undefined {
+  if (!raw) {
+    return undefined;
+  }
+  const match = /(?:^|;)messageid=([^;]+)/i.exec(raw);
+  const value = match?.[1]?.trim() ?? "";
+  return value || undefined;
+}
+
+export function parseMSTeamsActivityTimestamp(value: unknown): Date | undefined {
+  if (!value) {
+    return undefined;
+  }
+  if (value instanceof Date) {
+    return value;
+  }
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? undefined : date;
+}
+
+export function stripMSTeamsMentionTags(text: string): string {
+  // Teams wraps mentions in <at>...</at> tags
+  return text.replace(/<at[^>]*>.*?<\/at>/gi, "").trim();
+}
+
+/**
+ * Bot Framework uses 'a:xxx' conversation IDs for personal chats, but Graph API
+ * requires the '19:{userId}_{botAppId}@unq.gbl.spaces' format.
+ *
+ * This is the documented Graph API format for 1:1 chat thread IDs between a user
+ * and a bot/app. See Microsoft docs "Get chat between user and app":
+ * https://learn.microsoft.com/en-us/graph/api/userscopeteamsappinstallation-get-chat
+ *
+ * The format is only synthesized when the Bot Framework conversation ID starts with
+ * 'a:' (the opaque format used by BF but not recognized by Graph). If the ID already
+ * has the '19:...' Graph format, it is passed through unchanged.
+ */
+export function translateMSTeamsDmConversationIdForGraph(params: {
+  isDirectMessage: boolean;
+  conversationId: string;
+  aadObjectId?: string | null;
+  appId?: string | null;
+}): string {
+  const { isDirectMessage, conversationId, aadObjectId, appId } = params;
+  return isDirectMessage && conversationId.startsWith("a:") && aadObjectId && appId
+    ? `19:${aadObjectId}_${appId}@unq.gbl.spaces`
+    : conversationId;
+}
+
+export function wasMSTeamsBotMentioned(activity: MentionableActivity): boolean {
+  const botId = activity.recipient?.id;
+  if (!botId) {
+    return false;
+  }
+  const entities = activity.entities ?? [];
+  return entities.some((e) => e.type === "mention" && e.mentioned?.id === botId);
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { monitorMSTeamsProvider } from "./monitor.js";
+export { probeMSTeams } from "./probe.js";
+export { sendMessageMSTeams, sendPollMSTeams } from "./send.js";
+export { type MSTeamsCredentials, resolveMSTeamsCredentials } from "./token.js";