@openclaw/msteams 2026.3.13 → 2026.5.2-beta.1

package/src/graph.ts

@@ -1,8 +1,11 @@
-import type { MSTeamsConfig } from "openclaw/plugin-sdk/msteams";
+import { fetchWithSsrFGuard, type MSTeamsConfig } from "../runtime-api.js";
 import { GRAPH_ROOT } from "./attachments/shared.js";
-import { loadMSTeamsSdkWithAuth } from "./sdk.js";
+
+const GRAPH_BETA = "https://graph.microsoft.com/beta";
+import { createMSTeamsTokenProvider, loadMSTeamsSdkWithAuth } from "./sdk.js";
 import { readAccessToken } from "./token-response.js";
-import { resolveMSTeamsCredentials } from "./token.js";
+import { resolveDelegatedAccessToken, resolveMSTeamsCredentials } from "./token.js";
+import { buildUserAgent } from "./user-agent.js";
 
 export type GraphUser = {
   id?: string;
@@ -11,12 +14,12 @@ export type GraphUser = {
   mail?: string;
 };
 
-export type GraphGroup = {
+type GraphGroup = {
   id?: string;
   displayName?: string;
 };
 
-export type GraphChannel = {
+type GraphChannel = {
   id?: string;
   displayName?: string;
 };
@@ -31,35 +34,186 @@ export function escapeOData(value: string): string {
   return value.replace(/'/g, "''");
 }
 
-export async function fetchGraphJson<T>(params: {
+async function requestGraph(params: {
   token: string;
   path: string;
+  method?: "GET" | "POST" | "PATCH" | "DELETE";
+  root?: string;
   headers?: Record<string, string>;
-}): Promise<T> {
-  const res = await fetch(`${GRAPH_ROOT}${params.path}`, {
+  body?: unknown;
+  errorPrefix?: string;
+}): Promise<Response> {
+  const hasBody = params.body !== undefined;
+  const res = await fetch(`${params.root ?? GRAPH_ROOT}${params.path}`, {
+    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,
   });
   if (!res.ok) {
     const text = await res.text().catch(() => "");
-    throw new Error(`Graph ${params.path} failed (${res.status}): ${text || "unknown error"}`);
+    throw new Error(
+      `${params.errorPrefix ?? "Graph"} ${params.path} failed (${res.status}): ${text || "unknown error"}`,
+    );
+  }
+  return res;
+}
+
+async function readOptionalGraphJson<T>(res: Response): 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 res.json()) as T;
 }
 
-export async function resolveGraphToken(cfg: unknown): Promise<string> {
-  const creds = resolveMSTeamsCredentials(
-    (cfg as { channels?: { msteams?: unknown } })?.channels?.msteams as MSTeamsConfig | undefined,
-  );
+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);
+}
+
+/**
+ * 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 response.json()) as T;
+  } 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");
   }
-  const { sdk, authConfig } = await loadMSTeamsSdkWithAuth(creds);
-  const tokenProvider = new sdk.MsalTokenProvider(authConfig);
-  const token = await tokenProvider.getAccessToken("https://graph.microsoft.com");
-  const accessToken = readAccessToken(token);
+
+  // 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");
   }
@@ -70,12 +224,70 @@ export async function listTeamsByName(token: string, query: string): Promise<Gra
   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 res = await fetchGraphJson<GraphResponse<GraphGroup>>({ token, path });
-  return res.value ?? [];
+  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);
+}
+
+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);
+}
+
+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",
+  });
+  if (res.status === 204 || res.headers.get("content-length") === "0") {
+    return undefined as T;
+  }
+  return (await res.json()) as T;
 }
 
 export async function listChannelsForTeam(token: string, teamId: string): Promise<GraphChannel[]> {
   const path = `/teams/${encodeURIComponent(teamId)}/channels?$select=id,displayName`;
-  const res = await fetchGraphJson<GraphResponse<GraphChannel>>({ token, path });
-  return res.value ?? [];
+  const { items } = await fetchAllGraphPages<GraphChannel>({ token, path, maxPages: 10 });
+  return items;
 }

package/src/inbound.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, it } from "vitest";
 import {
+  decodeHtmlEntities,
+  extractMSTeamsQuoteInfo,
+  htmlToPlainText,
   normalizeMSTeamsConversationId,
   parseMSTeamsActivityTimestamp,
   stripMSTeamsMentionTags,
@@ -35,7 +38,10 @@ describe("msteams inbound", () => {
 
     it("parses string timestamps", () => {
       const ts = parseMSTeamsActivityTimestamp("2024-01-01T00:00:00.000Z");
-      expect(ts?.toISOString()).toBe("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", () => {
@@ -63,4 +69,153 @@ describe("msteams inbound", () => {
       ).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

@@ -1,4 +1,80 @@
-export type MentionableActivity = {
+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;
@@ -38,6 +114,30 @@ export function stripMSTeamsMentionTags(text: string): string {
   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) {

package/src/media-helpers.ts

@@ -8,7 +8,7 @@ import {
   extensionForMime,
   extractOriginalFilename,
   getFileExtension,
-} from "openclaw/plugin-sdk/msteams";
+} from "../runtime-api.js";
 
 /**
  * Detect MIME type from URL extension or data URL.