@openclaw/msteams 2026.3.13 → 2026.5.2-beta.1

package/src/attachments.graph.test.ts

@@ -0,0 +1,342 @@
+import { mockPinnedHostnameResolution } from "openclaw/plugin-sdk/test-env";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { PluginRuntime } from "../runtime-api.js";
+import { readRemoteMediaResponse } from "./attachments.test-helpers.js";
+import { downloadMSTeamsGraphMedia } from "./attachments/graph.js";
+import { resolveRequestUrl } from "./attachments/shared.js";
+import { setMSTeamsRuntime } from "./runtime.js";
+
+const GRAPH_HOST = "graph.microsoft.com";
+const SHAREPOINT_HOST = "contoso.sharepoint.com";
+const DEFAULT_MESSAGE_URL = `https://${GRAPH_HOST}/v1.0/chats/19%3Achat/messages/123`;
+const GRAPH_SHARES_URL_PREFIX = `https://${GRAPH_HOST}/v1.0/shares/`;
+const DEFAULT_MAX_BYTES = 1024 * 1024;
+const DEFAULT_SHAREPOINT_ALLOW_HOSTS = [GRAPH_HOST, SHAREPOINT_HOST];
+const DEFAULT_SHARE_REFERENCE_URL = `https://${SHAREPOINT_HOST}/site/file`;
+const CONTENT_TYPE_IMAGE_PNG = "image/png";
+const CONTENT_TYPE_APPLICATION_PDF = "application/pdf";
+const PNG_BUFFER = Buffer.from("png");
+
+const detectMimeMock = vi.fn(async () => CONTENT_TYPE_IMAGE_PNG);
+const saveMediaBufferMock = vi.fn(async () => ({
+  id: "saved.png",
+  path: "/tmp/saved.png",
+  size: Buffer.byteLength(PNG_BUFFER),
+  contentType: CONTENT_TYPE_IMAGE_PNG,
+}));
+const fetchRemoteMediaMock = vi.fn(
+  async (params: {
+    url: string;
+    maxBytes?: number;
+    filePathHint?: string;
+    fetchImpl?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+  }) => {
+    const fetchFn = params.fetchImpl ?? fetch;
+    const res = await fetchFn(params.url, { redirect: "manual" });
+    return readRemoteMediaResponse(res, params);
+  },
+);
+
+const runtimeStub = {
+  media: {
+    detectMime: detectMimeMock,
+  },
+  channel: {
+    media: {
+      fetchRemoteMedia: fetchRemoteMediaMock,
+      saveMediaBuffer: saveMediaBufferMock,
+    },
+  },
+} as unknown as PluginRuntime;
+
+type DownloadGraphMediaParams = Parameters<typeof downloadMSTeamsGraphMedia>[0];
+type DownloadGraphMediaOverrides = Partial<
+  Omit<DownloadGraphMediaParams, "messageUrl" | "tokenProvider">
+>;
+type FetchFn = typeof fetch;
+type LabeledCase = { label: string };
+type GraphFetchMockOptions = {
+  hostedContents?: unknown[];
+  attachments?: unknown[];
+  messageAttachments?: unknown[];
+  onShareRequest?: (url: string) => Response | Promise<Response>;
+  onUnhandled?: (url: string) => Response | Promise<Response> | undefined;
+};
+type GraphMediaDownloadResult = {
+  fetchMock: ReturnType<typeof createGraphFetchMock>;
+  media: Awaited<ReturnType<typeof downloadMSTeamsGraphMedia>>;
+};
+type GraphMediaSuccessCase = LabeledCase & {
+  buildOptions: () => GraphFetchMockOptions;
+  expectedLength: number;
+  assert?: (params: GraphMediaDownloadResult) => void;
+};
+
+const withLabel = <T extends object>(label: string, fields: T): T & LabeledCase => ({
+  label,
+  ...fields,
+});
+const createTokenProvider = (
+  tokenOrResolver: string | ((scope: string) => string | Promise<string>) = "token",
+) => ({
+  getAccessToken: vi.fn(async (scope: string) =>
+    typeof tokenOrResolver === "function" ? await tokenOrResolver(scope) : tokenOrResolver,
+  ),
+});
+const createBufferResponse = (payload: Buffer | string, contentType: string, status = 200) => {
+  const raw = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+  return new Response(new Uint8Array(raw), {
+    status,
+    headers: { "content-type": contentType },
+  });
+};
+const createPdfResponse = (payload: Buffer | string = Buffer.from("pdf")) =>
+  createBufferResponse(payload, CONTENT_TYPE_APPLICATION_PDF);
+const createJsonResponse = (payload: unknown, status = 200) =>
+  new Response(JSON.stringify(payload), { status });
+const createGraphCollectionResponse = (value: unknown[]) => createJsonResponse({ value });
+const createNotFoundResponse = () => new Response("not found", { status: 404 });
+const createRedirectResponse = (location: string, status = 302) =>
+  new Response(null, { status, headers: { location } });
+const asFetchFn = (fetchFn: unknown): FetchFn => fetchFn as FetchFn;
+const expectAttachmentMediaLength = (
+  media: Awaited<ReturnType<typeof downloadMSTeamsGraphMedia>>["media"],
+  expectedLength: number,
+) => {
+  expect(media).toHaveLength(expectedLength);
+};
+const expectMediaBufferSaved = () => {
+  expect(saveMediaBufferMock).toHaveBeenCalled();
+};
+
+const createHostedContentsWithType = (contentType: string, ...ids: string[]) =>
+  ids.map((id) => ({ id, contentType, contentBytes: PNG_BUFFER.toString("base64") }));
+const createHostedImageContents = (...ids: string[]) =>
+  createHostedContentsWithType(CONTENT_TYPE_IMAGE_PNG, ...ids);
+const createReferenceAttachment = (shareUrl = DEFAULT_SHARE_REFERENCE_URL) => ({
+  id: "ref-1",
+  contentType: "reference",
+  contentUrl: shareUrl,
+  name: "report.pdf",
+});
+const buildShareReferenceGraphFetchOptions = (params: {
+  referenceAttachment: ReturnType<typeof createReferenceAttachment>;
+  onShareRequest?: GraphFetchMockOptions["onShareRequest"];
+  onUnhandled?: GraphFetchMockOptions["onUnhandled"];
+}) => ({
+  attachments: [params.referenceAttachment],
+  messageAttachments: [params.referenceAttachment],
+  ...(params.onShareRequest ? { onShareRequest: params.onShareRequest } : {}),
+  ...(params.onUnhandled ? { onUnhandled: params.onUnhandled } : {}),
+});
+const buildDefaultShareReferenceGraphFetchOptions = (
+  params: Omit<Parameters<typeof buildShareReferenceGraphFetchOptions>[0], "referenceAttachment">,
+) =>
+  buildShareReferenceGraphFetchOptions({
+    referenceAttachment: createReferenceAttachment(),
+    ...params,
+  });
+type GraphEndpointResponseHandler = {
+  suffix: string;
+  buildResponse: () => Response;
+};
+const createGraphEndpointResponseHandlers = (params: {
+  hostedContents: unknown[];
+  attachments: unknown[];
+  messageAttachments: unknown[];
+}): GraphEndpointResponseHandler[] => [
+  {
+    suffix: "/hostedContents",
+    buildResponse: () => createGraphCollectionResponse(params.hostedContents),
+  },
+  {
+    suffix: "/attachments",
+    buildResponse: () => createGraphCollectionResponse(params.attachments),
+  },
+  {
+    suffix: "/messages/123",
+    buildResponse: () => createJsonResponse({ attachments: params.messageAttachments }),
+  },
+];
+const resolveGraphEndpointResponse = (
+  url: string,
+  handlers: GraphEndpointResponseHandler[],
+): Response | undefined => {
+  const handler = handlers.find((entry) => url.endsWith(entry.suffix));
+  return handler ? handler.buildResponse() : undefined;
+};
+
+const createGraphFetchMock = (options: GraphFetchMockOptions = {}) => {
+  const hostedContents = options.hostedContents ?? [];
+  const attachments = options.attachments ?? [];
+  const messageAttachments = options.messageAttachments ?? [];
+  const endpointHandlers = createGraphEndpointResponseHandlers({
+    hostedContents,
+    attachments,
+    messageAttachments,
+  });
+  return vi.fn(async (url: string) => {
+    const endpointResponse = resolveGraphEndpointResponse(url, endpointHandlers);
+    if (endpointResponse) {
+      return endpointResponse;
+    }
+    if (url.startsWith(GRAPH_SHARES_URL_PREFIX) && options.onShareRequest) {
+      return options.onShareRequest(url);
+    }
+    const unhandled = options.onUnhandled ? await options.onUnhandled(url) : undefined;
+    return unhandled ?? createNotFoundResponse();
+  });
+};
+const downloadGraphMediaWithMockOptions = async (
+  options: GraphFetchMockOptions = {},
+  overrides: DownloadGraphMediaOverrides = {},
+): Promise<GraphMediaDownloadResult> => {
+  const fetchMock = createGraphFetchMock(options);
+  const media = await downloadMSTeamsGraphMedia({
+    messageUrl: DEFAULT_MESSAGE_URL,
+    tokenProvider: createTokenProvider(),
+    maxBytes: DEFAULT_MAX_BYTES,
+    fetchFn: asFetchFn(fetchMock),
+    ...overrides,
+  });
+  return { fetchMock, media };
+};
+const runGraphMediaSuccessCase = async ({
+  buildOptions,
+  expectedLength,
+  assert,
+}: GraphMediaSuccessCase) => {
+  const { fetchMock, media } = await downloadGraphMediaWithMockOptions(buildOptions());
+  expectAttachmentMediaLength(media.media, expectedLength);
+  assert?.({ fetchMock, media });
+};
+
+const GRAPH_MEDIA_SUCCESS_CASES: GraphMediaSuccessCase[] = [
+  withLabel("downloads hostedContents images", {
+    buildOptions: () => ({ hostedContents: createHostedImageContents("1") }),
+    expectedLength: 1,
+    assert: ({ fetchMock }) => {
+      expect(fetchMock).toHaveBeenCalled();
+      expectMediaBufferSaved();
+    },
+  }),
+  withLabel("merges SharePoint reference attachments with hosted content", {
+    buildOptions: () => {
+      return {
+        hostedContents: createHostedImageContents("hosted-1"),
+        ...buildDefaultShareReferenceGraphFetchOptions({
+          onShareRequest: () => createPdfResponse(),
+        }),
+      };
+    },
+    expectedLength: 2,
+  }),
+];
+
+describe("msteams graph attachments", () => {
+  let ssrfMock: { mockRestore: () => void } | undefined;
+
+  beforeEach(() => {
+    ssrfMock?.mockRestore();
+    ssrfMock = mockPinnedHostnameResolution();
+    detectMimeMock.mockClear();
+    fetchRemoteMediaMock.mockClear();
+    saveMediaBufferMock.mockClear();
+    setMSTeamsRuntime(runtimeStub);
+  });
+
+  it.each<GraphMediaSuccessCase>(GRAPH_MEDIA_SUCCESS_CASES)("$label", runGraphMediaSuccessCase);
+
+  it("does not forward Authorization for SharePoint redirects outside auth allowlist", async () => {
+    const tokenProvider = createTokenProvider("top-secret-token");
+    const escapedUrl = "https://example.com/collect";
+    const seen: Array<{ url: string; auth: string }> = [];
+    const referenceAttachment = createReferenceAttachment();
+    const fetchMock = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = resolveRequestUrl(input);
+      const auth = new Headers(init?.headers).get("Authorization") ?? "";
+      seen.push({ url, auth });
+
+      if (url === DEFAULT_MESSAGE_URL) {
+        return createJsonResponse({ attachments: [referenceAttachment] });
+      }
+      if (url === `${DEFAULT_MESSAGE_URL}/hostedContents`) {
+        return createGraphCollectionResponse([]);
+      }
+      if (url === `${DEFAULT_MESSAGE_URL}/attachments`) {
+        return createGraphCollectionResponse([referenceAttachment]);
+      }
+      if (url.startsWith(GRAPH_SHARES_URL_PREFIX)) {
+        return createRedirectResponse(escapedUrl);
+      }
+      if (url === escapedUrl) {
+        return createPdfResponse();
+      }
+      return createNotFoundResponse();
+    });
+
+    const media = await downloadMSTeamsGraphMedia({
+      messageUrl: DEFAULT_MESSAGE_URL,
+      tokenProvider,
+      maxBytes: DEFAULT_MAX_BYTES,
+      allowHosts: [...DEFAULT_SHAREPOINT_ALLOW_HOSTS, "example.com"],
+      authAllowHosts: DEFAULT_SHAREPOINT_ALLOW_HOSTS,
+      fetchFn: asFetchFn(fetchMock),
+    });
+
+    expectAttachmentMediaLength(media.media, 1);
+    const redirected = seen.find((entry) => entry.url === escapedUrl);
+    expect(redirected).toBeDefined();
+    expect(redirected?.auth).toBe("");
+  });
+
+  it("blocks SharePoint redirects to hosts outside allowHosts", async () => {
+    const escapedUrl = "https://evil.example/internal.pdf";
+    const { fetchMock, media } = await downloadGraphMediaWithMockOptions(
+      {
+        ...buildDefaultShareReferenceGraphFetchOptions({
+          onShareRequest: () => createRedirectResponse(escapedUrl),
+          onUnhandled: (url) => {
+            if (url === escapedUrl) {
+              return createPdfResponse("should-not-be-fetched");
+            }
+            return undefined;
+          },
+        }),
+      },
+      {
+        allowHosts: DEFAULT_SHAREPOINT_ALLOW_HOSTS,
+      },
+    );
+
+    expectAttachmentMediaLength(media.media, 0);
+    const calledUrls = fetchMock.mock.calls.map((call) => call[0]);
+    expect(calledUrls.some((url) => url.startsWith(GRAPH_SHARES_URL_PREFIX))).toBe(true);
+    expect(calledUrls).not.toContain(escapedUrl);
+  });
+
+  it("skips inline hosted content when estimated decoded bytes exceed maxBytes", async () => {
+    const oversizedBase64 = "A".repeat(16);
+    const bufferFromSpy = vi.spyOn(Buffer, "from");
+
+    try {
+      const { media } = await downloadGraphMediaWithMockOptions(
+        {
+          hostedContents: [
+            {
+              id: "hosted-oversized",
+              contentType: CONTENT_TYPE_IMAGE_PNG,
+              contentBytes: oversizedBase64,
+            },
+          ],
+        },
+        { maxBytes: 4 },
+      );
+
+      expect(media.media).toEqual([]);
+      expect(bufferFromSpy).not.toHaveBeenCalledWith(oversizedBase64, "base64");
+    } finally {
+      bufferFromSpy.mockRestore();
+    }
+  });
+});

package/src/attachments.helpers.test.ts

@@ -0,0 +1,246 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import type { PluginRuntime } from "../runtime-api.js";
+import {
+  buildMSTeamsAttachmentPlaceholder,
+  buildMSTeamsGraphMessageUrls,
+  buildMSTeamsMediaPayload,
+} from "./attachments.js";
+import { setMSTeamsRuntime } from "./runtime.js";
+
+const _GRAPH_HOST = "graph.microsoft.com";
+const SHAREPOINT_HOST = "contoso.sharepoint.com";
+const TEST_HOST = "x";
+const createUrlForHost = (host: string, pathSegment: string) => `https://${host}/${pathSegment}`;
+const createTestUrl = (pathSegment: string) => createUrlForHost(TEST_HOST, pathSegment);
+const TEST_URL_IMAGE = createTestUrl("img");
+const TEST_URL_IMAGE_PNG = createTestUrl("img.png");
+const TEST_URL_IMAGE_1_PNG = createTestUrl("1.png");
+const TEST_URL_IMAGE_2_JPG = createTestUrl("2.jpg");
+const TEST_URL_PDF = createTestUrl("x.pdf");
+const TEST_URL_PDF_1 = createTestUrl("1.pdf");
+const TEST_URL_PDF_2 = createTestUrl("2.pdf");
+const TEST_URL_HTML_A = createTestUrl("a.png");
+const TEST_URL_HTML_B = createTestUrl("b.png");
+const CONTENT_TYPE_IMAGE_PNG = "image/png";
+const CONTENT_TYPE_APPLICATION_PDF = "application/pdf";
+const CONTENT_TYPE_TEXT_HTML = "text/html";
+const CONTENT_TYPE_TEAMS_FILE_DOWNLOAD_INFO = "application/vnd.microsoft.teams.file.download.info";
+type AttachmentPlaceholderInput = Parameters<typeof buildMSTeamsAttachmentPlaceholder>[0];
+type GraphMessageUrlParams = Parameters<typeof buildMSTeamsGraphMessageUrls>[0];
+type MSTeamsMediaPayload = ReturnType<typeof buildMSTeamsMediaPayload>;
+
+const runtimeStub = {
+  channel: {
+    text: {
+      chunkText: (text: string) => (text ? [text] : []),
+    },
+  },
+} as unknown as PluginRuntime;
+const MEDIA_PLACEHOLDER_IMAGE = "<media:image>";
+const MEDIA_PLACEHOLDER_DOCUMENT = "<media:document>";
+const formatImagePlaceholder = (count: number) =>
+  count > 1 ? `${MEDIA_PLACEHOLDER_IMAGE} (${count} images)` : MEDIA_PLACEHOLDER_IMAGE;
+const formatDocumentPlaceholder = (count: number) =>
+  count > 1 ? `${MEDIA_PLACEHOLDER_DOCUMENT} (${count} files)` : MEDIA_PLACEHOLDER_DOCUMENT;
+const withLabel = <T extends object>(label: string, fields: T): T & { label: string } => ({
+  label,
+  ...fields,
+});
+const buildAttachment = <T extends Record<string, unknown>>(contentType: string, props: T) => ({
+  contentType,
+  ...props,
+});
+const createHtmlAttachment = (content: string) =>
+  buildAttachment(CONTENT_TYPE_TEXT_HTML, { content });
+const buildHtmlImageTag = (src: string) => `<img src="${src}" />`;
+const createHtmlImageAttachments = (sources: string[], prefix = "") => [
+  createHtmlAttachment(`${prefix}${sources.map(buildHtmlImageTag).join("")}`),
+];
+const createContentUrlAttachments = (contentType: string, ...contentUrls: string[]) =>
+  contentUrls.map((contentUrl) => buildAttachment(contentType, { contentUrl }));
+const createImageAttachments = (...contentUrls: string[]) =>
+  createContentUrlAttachments(CONTENT_TYPE_IMAGE_PNG, ...contentUrls);
+const createPdfAttachments = (...contentUrls: string[]) =>
+  createContentUrlAttachments(CONTENT_TYPE_APPLICATION_PDF, ...contentUrls);
+const createTeamsFileDownloadInfoAttachments = (
+  downloadUrl = createTestUrl("dl"),
+  fileType = "png",
+) => [
+  buildAttachment(CONTENT_TYPE_TEAMS_FILE_DOWNLOAD_INFO, {
+    content: { downloadUrl, fileType },
+  }),
+];
+const createMediaEntriesWithType = (contentType: string, ...paths: string[]) =>
+  paths.map((path) => ({ path, contentType }));
+const createImageMediaEntries = (...paths: string[]) =>
+  createMediaEntriesWithType(CONTENT_TYPE_IMAGE_PNG, ...paths);
+const DEFAULT_CHANNEL_TEAM_ID = "team-id";
+const DEFAULT_CHANNEL_ID = "chan-id";
+const createChannelGraphMessageUrlParams = (params: {
+  messageId: string;
+  replyToId?: string;
+  conversationId?: string;
+}) => ({
+  conversationType: "channel" as const,
+  ...params,
+  channelData: {
+    team: { id: DEFAULT_CHANNEL_TEAM_ID },
+    channel: { id: DEFAULT_CHANNEL_ID },
+  },
+});
+const buildExpectedChannelMessagePath = (params: { messageId: string; replyToId?: string }) =>
+  params.replyToId
+    ? `/teams/${DEFAULT_CHANNEL_TEAM_ID}/channels/${DEFAULT_CHANNEL_ID}/messages/${params.replyToId}/replies/${params.messageId}`
+    : `/teams/${DEFAULT_CHANNEL_TEAM_ID}/channels/${DEFAULT_CHANNEL_ID}/messages/${params.messageId}`;
+
+const expectMSTeamsMediaPayload = (
+  payload: MSTeamsMediaPayload,
+  expected: { firstPath: string; paths: string[]; types: string[] },
+) => {
+  expect(payload.MediaPath).toBe(expected.firstPath);
+  expect(payload.MediaUrl).toBe(expected.firstPath);
+  expect(payload.MediaPaths).toEqual(expected.paths);
+  expect(payload.MediaUrls).toEqual(expected.paths);
+  expect(payload.MediaTypes).toEqual(expected.types);
+};
+
+const ATTACHMENT_PLACEHOLDER_CASES = [
+  withLabel("returns empty string when no attachments", {
+    attachments: undefined as AttachmentPlaceholderInput,
+    expected: "",
+  }),
+  withLabel("returns empty string when attachments are empty", {
+    attachments: [],
+    expected: "",
+  }),
+  withLabel("returns image placeholder for one image attachment", {
+    attachments: createImageAttachments(TEST_URL_IMAGE_PNG),
+    expected: formatImagePlaceholder(1),
+  }),
+  withLabel("returns image placeholder with count for many image attachments", {
+    attachments: [
+      ...createImageAttachments(TEST_URL_IMAGE_1_PNG),
+      { contentType: "image/jpeg", contentUrl: TEST_URL_IMAGE_2_JPG },
+    ],
+    expected: formatImagePlaceholder(2),
+  }),
+  withLabel("treats Teams file.download.info image attachments as images", {
+    attachments: createTeamsFileDownloadInfoAttachments(),
+    expected: formatImagePlaceholder(1),
+  }),
+  withLabel("returns document placeholder for non-image attachments", {
+    attachments: createPdfAttachments(TEST_URL_PDF),
+    expected: formatDocumentPlaceholder(1),
+  }),
+  withLabel("returns document placeholder with count for many non-image attachments", {
+    attachments: createPdfAttachments(TEST_URL_PDF_1, TEST_URL_PDF_2),
+    expected: formatDocumentPlaceholder(2),
+  }),
+  withLabel("counts one inline image in html attachments", {
+    attachments: createHtmlImageAttachments([TEST_URL_HTML_A], "<p>hi</p>"),
+    expected: formatImagePlaceholder(1),
+  }),
+  withLabel("counts many inline images in html attachments", {
+    attachments: createHtmlImageAttachments([TEST_URL_HTML_A, TEST_URL_HTML_B]),
+    expected: formatImagePlaceholder(2),
+  }),
+];
+
+const GRAPH_URL_EXPECTATION_CASES = [
+  withLabel("builds channel message urls", {
+    params: createChannelGraphMessageUrlParams({
+      conversationId: "19:thread@thread.tacv2",
+      messageId: "123",
+    }),
+    expectedPath: buildExpectedChannelMessagePath({ messageId: "123" }),
+  }),
+  withLabel("builds channel reply urls when replyToId is present", {
+    params: createChannelGraphMessageUrlParams({
+      messageId: "reply-id",
+      replyToId: "root-id",
+    }),
+    expectedPath: buildExpectedChannelMessagePath({
+      messageId: "reply-id",
+      replyToId: "root-id",
+    }),
+  }),
+  withLabel("builds chat message urls", {
+    params: {
+      conversationType: "groupChat" as const,
+      conversationId: "19:chat@thread.v2",
+      messageId: "456",
+    } satisfies GraphMessageUrlParams,
+    expectedPath: "/chats/19%3Achat%40thread.v2/messages/456",
+  }),
+];
+
+describe("msteams attachment helpers", () => {
+  beforeEach(() => {
+    setMSTeamsRuntime(runtimeStub);
+  });
+
+  describe("buildMSTeamsAttachmentPlaceholder", () => {
+    it.each(ATTACHMENT_PLACEHOLDER_CASES)("$label", ({ attachments, expected }) => {
+      expect(buildMSTeamsAttachmentPlaceholder(attachments)).toBe(expected);
+    });
+
+    it("respects inline image limits when counting placeholder images", () => {
+      const attachments = [
+        {
+          contentType: "text/html",
+          content: `<img src="data:image/png;base64,${"A".repeat(16)}" />`,
+        },
+      ];
+
+      expect(
+        buildMSTeamsAttachmentPlaceholder(attachments, {
+          maxInlineBytes: 4,
+          maxInlineTotalBytes: 4,
+        }),
+      ).toBe("<media:document>");
+    });
+  });
+
+  describe("buildMSTeamsGraphMessageUrls", () => {
+    it.each(GRAPH_URL_EXPECTATION_CASES)("$label", ({ params, expectedPath }) => {
+      const urls = buildMSTeamsGraphMessageUrls(params);
+      expect(urls[0]).toContain(expectedPath);
+    });
+
+    it("uses resolved Graph chat ID for personal DMs instead of Bot Framework a: ID", () => {
+      const urls = buildMSTeamsGraphMessageUrls({
+        conversationType: "personal",
+        conversationId: "19:real-graph-chat-id@unq.gbl.spaces",
+        messageId: "msg-1",
+      });
+      expect(urls).toHaveLength(1);
+      expect(urls[0]).toContain("/chats/19%3Areal-graph-chat-id%40unq.gbl.spaces/messages/msg-1");
+    });
+
+    it("still builds URLs when a: conversation ID is passed (caller did not resolve)", () => {
+      const urls = buildMSTeamsGraphMessageUrls({
+        conversationType: "personal",
+        conversationId: "a:1dRsHCobZ1AxURzY",
+        messageId: "msg-1",
+      });
+      expect(urls).toHaveLength(1);
+      expect(urls[0]).toContain("/chats/a%3A1dRsHCobZ1AxURzY/messages/msg-1");
+    });
+  });
+
+  describe("buildMSTeamsMediaPayload", () => {
+    it("returns single and multi-file fields", () => {
+      const payload = buildMSTeamsMediaPayload(createImageMediaEntries("/tmp/a.png", "/tmp/b.png"));
+      expectMSTeamsMediaPayload(payload, {
+        firstPath: "/tmp/a.png",
+        paths: ["/tmp/a.png", "/tmp/b.png"],
+        types: [CONTENT_TYPE_IMAGE_PNG, CONTENT_TYPE_IMAGE_PNG],
+      });
+    });
+  });
+
+  it("retains the expected sharepoint host fixture", () => {
+    expect(SHAREPOINT_HOST).toBe("contoso.sharepoint.com");
+    expect(TEST_URL_IMAGE).toContain(TEST_HOST);
+  });
+});

package/src/attachments.test-helpers.ts

@@ -0,0 +1,17 @@
+export async function readRemoteMediaResponse(
+  res: Response,
+  params: { maxBytes?: number; filePathHint?: string },
+) {
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status}`);
+  }
+  const buffer = Buffer.from(await res.arrayBuffer());
+  if (typeof params.maxBytes === "number" && buffer.byteLength > params.maxBytes) {
+    throw new Error(`payload exceeds maxBytes ${params.maxBytes}`);
+  }
+  return {
+    buffer,
+    contentType: res.headers.get("content-type") ?? undefined,
+    fileName: params.filePathHint,
+  };
+}