@copilotkit/channels-teams 0.1.0

package/dist/download-files.test.js

@@ -0,0 +1,96 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { buildFileContentParts } from "./download-files.js";
+const FILE_DOWNLOAD_INFO = "application/vnd.microsoft.teams.file.download.info";
+function mockFetch(body, init = {}) {
+    const bytes = typeof body === "string" ? new TextEncoder().encode(body) : body;
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({
+        ok: init.ok ?? true,
+        status: init.status ?? 200,
+        arrayBuffer: async () => bytes.buffer,
+    }));
+}
+afterEach(() => {
+    vi.unstubAllGlobals();
+});
+describe("buildFileContentParts (Teams)", () => {
+    it("downloads a CSV file.download.info attachment as a decoded text part", async () => {
+        mockFetch("a,b\n1,2\n");
+        const att = {
+            contentType: FILE_DOWNLOAD_INFO,
+            name: "data.csv",
+            content: {
+                downloadUrl: "https://files.example/data.csv",
+                fileType: "csv",
+            },
+        };
+        const { parts, notes } = await buildFileContentParts([att]);
+        expect(notes).toEqual([]);
+        expect(parts).toHaveLength(1);
+        expect(parts[0]).toMatchObject({ type: "text" });
+        const text = parts[0].text;
+        expect(text).toContain('Attached file "data.csv" (text/csv)');
+        expect(text).toContain("a,b\n1,2");
+        expect(fetch).toHaveBeenCalledWith("https://files.example/data.csv");
+    });
+    it("decodes a base64 data: URI image into an image part without fetching", async () => {
+        const fetchSpy = vi.fn();
+        vi.stubGlobal("fetch", fetchSpy);
+        const png = Buffer.from([0x89, 0x50, 0x4e, 0x47]).toString("base64");
+        const att = {
+            contentType: "image/png",
+            name: "chart.png",
+            contentUrl: `data:image/png;base64,${png}`,
+        };
+        const { parts } = await buildFileContentParts([att]);
+        expect(fetchSpy).not.toHaveBeenCalled();
+        expect(parts[0]).toMatchObject({
+            type: "image",
+            source: { type: "data", value: png, mimeType: "image/png" },
+        });
+    });
+    it("fetches an https image attachment and passes it through as binary", async () => {
+        mockFetch(new Uint8Array([1, 2, 3, 4]));
+        const att = {
+            contentType: "image/jpeg",
+            name: "photo.jpg",
+            contentUrl: "https://smba.example/v3/attachments/123",
+        };
+        const { parts } = await buildFileContentParts([att]);
+        expect(parts[0]).toMatchObject({
+            type: "image",
+            source: { type: "data", mimeType: "image/jpeg" },
+        });
+    });
+    it("notes a download failure instead of throwing", async () => {
+        mockFetch("", { ok: false, status: 404 });
+        const att = {
+            contentType: FILE_DOWNLOAD_INFO,
+            name: "data.csv",
+            content: { downloadUrl: "https://files.example/missing.csv" },
+        };
+        const { parts, notes } = await buildFileContentParts([att]);
+        expect(parts).toEqual([]);
+        expect(notes[0]).toContain("download failed (HTTP 404)");
+    });
+    it("skips an Adaptive Card attachment (no downloadable source)", async () => {
+        const att = {
+            contentType: "application/vnd.microsoft.card.adaptive",
+            content: { type: "AdaptiveCard" },
+        };
+        const { parts, notes } = await buildFileContentParts([att]);
+        expect(parts).toEqual([]);
+        expect(notes).toEqual([]);
+    });
+    it("caps the number of files processed", async () => {
+        mockFetch("x");
+        const make = (i) => ({
+            contentType: FILE_DOWNLOAD_INFO,
+            name: `f${i}.txt`,
+            content: { downloadUrl: `https://files.example/f${i}.txt` },
+        });
+        const atts = Array.from({ length: 7 }, (_, i) => make(i));
+        const { parts, notes } = await buildFileContentParts(atts, { maxFiles: 3 });
+        expect(parts).toHaveLength(3);
+        expect(notes.some((n) => n.includes("only the first 3 of 7"))).toBe(true);
+    });
+});

package/dist/event-renderer.d.ts

@@ -0,0 +1,23 @@
+import type { RunRenderer } from "@copilotkit/channels";
+/**
+ * Build a {@link RunRenderer} for a single agent run in Teams.
+ *
+ * Each AG-UI text message is **streamed by message edit**: on the first content
+ * delta we post a Teams message (after a typing indicator), then `updateActivity`
+ * it as the text grows (throttled), and finalize on message-end. This is Teams'
+ * baseline streaming model (see {@link TeamsMessageStream}). Tool calls and
+ * interrupts are captured for the run-loop to read after `runAgent` resolves,
+ * exactly as the Slack adapter does.
+ */
+export declare function createRunRenderer(args: {
+    /** First send for a streamed message. Returns the posted activity id. */
+    post: (text: string) => Promise<string>;
+    /** Edit a previously-posted streamed message. */
+    update: (id: string, text: string) => Promise<void>;
+    /** Optional typing indicator, fired once before a message's first post. */
+    typing?: () => Promise<void>;
+    interruptEventNames?: ReadonlySet<string>;
+    /** Persist the agent's reply text to the conversation transcript. */
+    recordAssistant?: (text: string) => void;
+}): RunRenderer;
+//# sourceMappingURL=event-renderer.d.ts.map

package/dist/event-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-renderer.d.ts","sourceRoot":"","sources":["../src/event-renderer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,WAAW,EAGZ,MAAM,sBAAsB,CAAC;AAM9B;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,yEAAyE;IACzE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,iDAAiD;IACjD,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,mBAAmB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,qEAAqE;IACrE,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1C,GAAG,WAAW,CAkId"}

package/dist/event-renderer.js

@@ -0,0 +1,135 @@
+import { TeamsMessageStream } from "./message-stream.js";
+import { autoCloseOpenMarkdown } from "./render/auto-close.js";
+const INTERRUPTED_SUFFIX = "\n\n_(interrupted)_";
+/**
+ * Build a {@link RunRenderer} for a single agent run in Teams.
+ *
+ * Each AG-UI text message is **streamed by message edit**: on the first content
+ * delta we post a Teams message (after a typing indicator), then `updateActivity`
+ * it as the text grows (throttled), and finalize on message-end. This is Teams'
+ * baseline streaming model (see {@link TeamsMessageStream}). Tool calls and
+ * interrupts are captured for the run-loop to read after `runAgent` resolves,
+ * exactly as the Slack adapter does.
+ */
+export function createRunRenderer(args) {
+    const interruptEventNames = args.interruptEventNames ?? new Set(["on_interrupt"]);
+    /** Per-AG-UI-message accumulated text + its streamed-by-edit message. */
+    const buffers = new Map();
+    const streams = new Map();
+    const capturedToolCalls = [];
+    let pendingInterrupt;
+    let aborted = false;
+    const streamFor = (messageId) => {
+        let s = streams.get(messageId);
+        if (!s) {
+            s = new TeamsMessageStream({
+                post: args.post,
+                update: args.update,
+                typing: args.typing,
+            });
+            streams.set(messageId, s);
+        }
+        return s;
+    };
+    const captureToolCall = (toolCallId, toolCallName, toolCallArgs) => {
+        const existing = capturedToolCalls.find((c) => c.toolCallId === toolCallId);
+        if (existing) {
+            existing.toolCallName = toolCallName;
+            existing.toolCallArgs = toolCallArgs;
+        }
+        else {
+            capturedToolCalls.push({ toolCallId, toolCallName, toolCallArgs });
+        }
+    };
+    const subscriber = {
+        onTextMessageStartEvent({ event }) {
+            if (aborted)
+                return;
+            buffers.set(event.messageId, "");
+            streamFor(event.messageId);
+        },
+        onTextMessageContentEvent({ event }) {
+            if (aborted)
+                return;
+            const next = (buffers.get(event.messageId) ?? "") + (event.delta ?? "");
+            buffers.set(event.messageId, next);
+            // Mid-stream the buffer is usually unbalanced markdown (an open `**`,
+            // code fence, etc.); balance it for display so the edited message never
+            // renders broken. The finalized message uses the raw text (below).
+            streamFor(event.messageId).append(autoCloseOpenMarkdown(next));
+        },
+        async onTextMessageEndEvent({ event }) {
+            if (aborted)
+                return;
+            const text = buffers.get(event.messageId) ?? "";
+            buffers.delete(event.messageId);
+            // Commit the agent's exact final text (now balanced on its own) so the
+            // settled message carries no synthetic closers.
+            const stream = streamFor(event.messageId);
+            stream.append(text);
+            await stream.finish();
+            streams.delete(event.messageId);
+            const trimmed = text.trim();
+            if (trimmed)
+                args.recordAssistant?.(trimmed);
+        },
+        onToolCallArgsEvent({ event, toolCallName, partialToolCallArgs }) {
+            if (aborted)
+                return;
+            captureToolCall(event.toolCallId, toolCallName, (partialToolCallArgs ?? {}));
+        },
+        onToolCallEndEvent({ event, toolCallName, toolCallArgs }) {
+            if (aborted)
+                return;
+            captureToolCall(event.toolCallId, toolCallName, (toolCallArgs ?? {}));
+        },
+        onCustomEvent({ event }) {
+            if (aborted)
+                return;
+            const e = event;
+            if (!e.name || !interruptEventNames.has(e.name))
+                return;
+            let value = e.value;
+            if (typeof value === "string") {
+                try {
+                    value = JSON.parse(value);
+                }
+                catch {
+                    // Leave as a string. The handler's schema rejects it explicitly.
+                }
+            }
+            pendingInterrupt = { eventName: e.name, value };
+        },
+        async onRunErrorEvent({ event }) {
+            if (aborted)
+                return;
+            await args.post(`⚠️ Agent error: ${event.message ?? "unknown error"}`);
+        },
+    };
+    return {
+        subscriber,
+        getCapturedToolCalls: () => capturedToolCalls,
+        getPendingInterrupt: () => pendingInterrupt,
+        clearPendingInterrupt: () => {
+            pendingInterrupt = undefined;
+        },
+        async markInterrupted() {
+            if (aborted)
+                return;
+            aborted = true;
+            // Flush any partial reply with a marker so the user sees the run stopped.
+            const tasks = [];
+            for (const [id, buf] of Array.from(buffers.entries())) {
+                const s = streams.get(id);
+                if (s && buf.length > 0) {
+                    // Balance the partial buffer so the interrupted marker reads cleanly.
+                    s.append(autoCloseOpenMarkdown(buf) + INTERRUPTED_SUFFIX);
+                    tasks.push(s.finish());
+                }
+                buffers.delete(id);
+                streams.delete(id);
+            }
+            await Promise.all(tasks);
+        },
+    };
+}

package/dist/event-renderer.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=event-renderer.test.d.ts.map

package/dist/event-renderer.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-renderer.test.d.ts","sourceRoot":"","sources":["../src/event-renderer.test.ts"],"names":[],"mappings":""}

package/dist/event-renderer.test.js

@@ -0,0 +1,95 @@
+import { describe, it, expect, vi } from "vitest";
+import { createRunRenderer } from "./event-renderer.js";
+/**
+ * Stub the four callbacks the renderer drives (`post` / `update` / `typing` /
+ * `recordAssistant`) and record every send in order. `post` returns a stable
+ * activity id so later edits address the same message.
+ */
+function makeSink() {
+    const posts = [];
+    const updates = [];
+    const recorded = [];
+    const typing = vi.fn(async () => { });
+    const post = vi.fn(async (text) => {
+        posts.push(text);
+        return "activity-1";
+    });
+    const update = vi.fn(async (id, text) => {
+        updates.push({ id, text });
+    });
+    const recordAssistant = vi.fn((text) => {
+        recorded.push(text);
+    });
+    return { posts, updates, recorded, typing, post, update, recordAssistant };
+}
+describe("createRunRenderer (Teams)", () => {
+    it("accumulates deltas into the final streamed message and records it", async () => {
+        // AG-UI delivers text one delta at a time; the renderer must accumulate
+        // them itself (not forward the lagging per-event buffer) so the settled
+        // Teams message reads "ECHO", not "E".
+        const sink = makeSink();
+        const { subscriber: sub } = createRunRenderer(sink);
+        const id = "msg-1";
+        await sub.onTextMessageStartEvent({
+            event: { messageId: id, role: "assistant" },
+        });
+        sub.onTextMessageContentEvent({
+            event: { messageId: id, delta: "E" },
+        });
+        sub.onTextMessageContentEvent({
+            event: { messageId: id, delta: "CHO" },
+        });
+        await sub.onTextMessageEndEvent({ event: { messageId: id } });
+        // Whatever the throttle split (single post, or post-then-edits), the last
+        // text Teams sees is the fully-accumulated reply.
+        const lastSent = sink.updates.at(-1)?.text ?? sink.posts.at(-1);
+        expect(lastSent).toBe("ECHO");
+        // A typing indicator fires once before the first post.
+        expect(sink.typing).toHaveBeenCalledTimes(1);
+        // The final text is committed to the conversation transcript.
+        expect(sink.recorded).toEqual(["ECHO"]);
+    });
+    it("captures tool calls for the run loop to read", async () => {
+        const sink = makeSink();
+        const renderer = createRunRenderer(sink);
+        renderer.subscriber.onToolCallEndEvent({
+            event: { toolCallId: "t1" },
+            toolCallName: "show_card",
+            toolCallArgs: { title: "Status" },
+        });
+        expect(renderer.getCapturedToolCalls()).toEqual([
+            {
+                toolCallId: "t1",
+                toolCallName: "show_card",
+                toolCallArgs: { title: "Status" },
+            },
+        ]);
+    });
+    it("captures a custom interrupt event and JSON-parses its value", async () => {
+        const sink = makeSink();
+        const renderer = createRunRenderer(sink);
+        renderer.subscriber.onCustomEvent({
+            event: { name: "on_interrupt", value: '{"confirmed":true}' },
+        });
+        expect(renderer.getPendingInterrupt()).toEqual({
+            eventName: "on_interrupt",
+            value: { confirmed: true },
+        });
+        renderer.clearPendingInterrupt();
+        expect(renderer.getPendingInterrupt()).toBeUndefined();
+    });
+    it("ignores custom events whose name isn't an interrupt", async () => {
+        const sink = makeSink();
+        const renderer = createRunRenderer(sink);
+        renderer.subscriber.onCustomEvent({
+            event: { name: "telemetry", value: "{}" },
+        });
+        expect(renderer.getPendingInterrupt()).toBeUndefined();
+    });
+    it("posts a visible message on a run error", async () => {
+        const sink = makeSink();
+        const { subscriber: sub } = createRunRenderer(sink);
+        await sub.onRunErrorEvent({ event: { message: "boom" } });
+        expect(sink.posts).toContain("⚠️ Agent error: boom");
+    });
+});

package/dist/graph-files.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Microsoft Graph file access for Teams CHANNEL messages.
+ *
+ * The Teams bot file API (the `file.download.info` attachment) only fires in a
+ * 1:1 personal chat. In a channel the bot's inbound activity carries no file at
+ * all — the upload lives in the team's SharePoint document library and is only
+ * referenced from the channel *message*, which the bot doesn't receive inline.
+ * So to chart "a CSV someone dropped in a channel" we go through Graph:
+ *
+ *   1. Acquire an app-only Graph token (client credentials — the same
+ *      clientId/clientSecret/tenantId the adapter already uses for Teams).
+ *   2. Read the channel message to find its file attachments
+ *      (`GET /teams/{team}/channels/{channel}/messages/{id}` — app-only via the
+ *      RSC permission `ChannelMessage.Read.Group`, declared in the app
+ *      manifest; no tenant admin consent or protected-API approval needed).
+ *   3. Download each referenced SharePoint file via the `/shares` endpoint
+ *      (needs the `Files.Read.All` application permission + admin consent).
+ *
+ * Returns nothing (with a note) when Graph isn't configured or a step fails, so
+ * the bot degrades to asking the user to paste the data rather than crashing.
+ */
+import { type FileDeliveryConfig } from "./download-files.js";
+import type { AgentContentPart } from "@copilotkit/channels-ui";
+/** The Microsoft credentials needed for an app-only Graph token. */
+export interface GraphCredentials {
+    clientId: string;
+    clientSecret: string;
+    tenantId: string;
+}
+/** Identifiers needed to read a channel message, pulled from the activity. */
+export interface ChannelMessageRef {
+    /** The team's Entra (AAD) group id — `channelData.team.aadGroupId`. */
+    teamId: string;
+    /** The channel thread id — `channelData.teamsChannelId`. */
+    channelId: string;
+    /** The inbound message id (`activity.id`). */
+    messageId: string;
+    /** Root message id when this is a reply; equals `messageId` for a top-level post. */
+    rootId: string;
+}
+/**
+ * Resolve a channel message's uploaded files into AG-UI content parts via
+ * Graph. Returns `{ parts, notes }`; on any failure the parts are empty and a
+ * note explains why (so the caller can tell the user to paste the data).
+ */
+export declare function buildChannelFileContentParts(ref: ChannelMessageRef, creds: GraphCredentials, config?: FileDeliveryConfig): Promise<{
+    parts: AgentContentPart[];
+    notes: string[];
+}>;
+//# sourceMappingURL=graph-files.d.ts.map

package/dist/graph-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-files.d.ts","sourceRoot":"","sources":["../src/graph-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,MAAM,EAAE,MAAM,CAAC;CAChB;AAwGD;;;;GAIG;AACH,wBAAsB,4BAA4B,CAChD,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,gBAAgB,EACvB,MAAM,GAAE,kBAAuB,GAC9B,OAAO,CAAC;IAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAwCzD"}

package/dist/graph-files.js

@@ -0,0 +1,126 @@
+/**
+ * Microsoft Graph file access for Teams CHANNEL messages.
+ *
+ * The Teams bot file API (the `file.download.info` attachment) only fires in a
+ * 1:1 personal chat. In a channel the bot's inbound activity carries no file at
+ * all — the upload lives in the team's SharePoint document library and is only
+ * referenced from the channel *message*, which the bot doesn't receive inline.
+ * So to chart "a CSV someone dropped in a channel" we go through Graph:
+ *
+ *   1. Acquire an app-only Graph token (client credentials — the same
+ *      clientId/clientSecret/tenantId the adapter already uses for Teams).
+ *   2. Read the channel message to find its file attachments
+ *      (`GET /teams/{team}/channels/{channel}/messages/{id}` — app-only via the
+ *      RSC permission `ChannelMessage.Read.Group`, declared in the app
+ *      manifest; no tenant admin consent or protected-API approval needed).
+ *   3. Download each referenced SharePoint file via the `/shares` endpoint
+ *      (needs the `Files.Read.All` application permission + admin consent).
+ *
+ * Returns nothing (with a note) when Graph isn't configured or a step fails, so
+ * the bot degrades to asking the user to paste the data rather than crashing.
+ */
+import { decodeFileBytes, mimeFromName, } from "./download-files.js";
+const GRAPH = "https://graph.microsoft.com/v1.0";
+// One cached app token per process; Graph tokens last ~1h. Date.now is fine here
+// (this is ordinary runtime code, not a replay-sensitive workflow script).
+let cachedToken;
+/** Acquire (and cache) an app-only Graph token via the client-credentials grant. */
+async function acquireAppToken(creds) {
+    const now = Date.now();
+    if (cachedToken && cachedToken.expiresAt > now + 60_000) {
+        return cachedToken.token;
+    }
+    const body = new URLSearchParams({
+        client_id: creds.clientId,
+        client_secret: creds.clientSecret,
+        scope: "https://graph.microsoft.com/.default",
+        grant_type: "client_credentials",
+    });
+    const res = await fetch(`https://login.microsoftonline.com/${creds.tenantId}/oauth2/v2.0/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body,
+    });
+    if (!res.ok) {
+        throw new Error(`Graph token request failed (HTTP ${res.status}): ${(await res.text()).slice(0, 200)}`);
+    }
+    const json = (await res.json());
+    cachedToken = {
+        token: json.access_token,
+        expiresAt: now + json.expires_in * 1000,
+    };
+    return cachedToken.token;
+}
+/** Encode a sharing URL into a Graph `/shares` share id (`u!<base64url>`). */
+function shareIdFor(url) {
+    const b64 = Buffer.from(url, "utf8").toString("base64");
+    return "u!" + b64.replace(/=+$/, "").replace(/\//g, "_").replace(/\+/g, "-");
+}
+/** Read a channel message and return its file-reference attachments. */
+async function getMessageFileRefs(ref, token) {
+    const channel = encodeURIComponent(ref.channelId);
+    const url = ref.rootId && ref.rootId !== ref.messageId
+        ? `${GRAPH}/teams/${ref.teamId}/channels/${channel}/messages/${ref.rootId}/replies/${ref.messageId}`
+        : `${GRAPH}/teams/${ref.teamId}/channels/${channel}/messages/${ref.messageId}`;
+    const res = await fetch(url, {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) {
+        throw new Error(`read channel message failed (HTTP ${res.status}): ${(await res.text()).slice(0, 200)}`);
+    }
+    const msg = (await res.json());
+    return (msg.attachments ?? [])
+        .filter((a) => a.contentType === "reference" && typeof a.contentUrl === "string")
+        .map((a) => ({ name: a.name ?? "file", contentUrl: a.contentUrl }));
+}
+/** Download a SharePoint file by its sharing URL via the Graph `/shares` API. */
+async function downloadSharedFile(contentUrl, token) {
+    const res = await fetch(`${GRAPH}/shares/${shareIdFor(contentUrl)}/driveItem/content`, { headers: { Authorization: `Bearer ${token}` }, redirect: "follow" });
+    if (!res.ok) {
+        throw new Error(`download failed (HTTP ${res.status})`);
+    }
+    return Buffer.from(await res.arrayBuffer());
+}
+/**
+ * Resolve a channel message's uploaded files into AG-UI content parts via
+ * Graph. Returns `{ parts, notes }`; on any failure the parts are empty and a
+ * note explains why (so the caller can tell the user to paste the data).
+ */
+export async function buildChannelFileContentParts(ref, creds, config = {}) {
+    const parts = [];
+    const notes = [];
+    let token;
+    try {
+        token = await acquireAppToken(creds);
+    }
+    catch (err) {
+        notes.push(`couldn't get a Graph token: ${err.message}`);
+        return { parts, notes };
+    }
+    let refs;
+    try {
+        refs = await getMessageFileRefs(ref, token);
+    }
+    catch (err) {
+        notes.push(`couldn't read channel-message files via Graph (is ChannelMessage.Read.Group granted?): ${err.message}`);
+        return { parts, notes };
+    }
+    const maxFiles = config.maxFiles ?? 5;
+    for (const f of refs.slice(0, maxFiles)) {
+        let bytes;
+        try {
+            bytes = await downloadSharedFile(f.contentUrl, token);
+        }
+        catch (err) {
+            notes.push(`skipped "${f.name}" (is Files.Read.All granted?): ${err.message}`);
+            continue;
+        }
+        const mime = mimeFromName(f.name) ?? "application/octet-stream";
+        const decoded = decodeFileBytes(f.name, mime, bytes, config);
+        if ("note" in decoded)
+            notes.push(decoded.note);
+        else
+            parts.push(decoded.part);
+    }
+    return { parts, notes };
+}

package/dist/graph-files.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=graph-files.test.d.ts.map

package/dist/graph-files.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-files.test.d.ts","sourceRoot":"","sources":["../src/graph-files.test.ts"],"names":[],"mappings":""}

package/dist/graph-files.test.js

@@ -0,0 +1,114 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { buildChannelFileContentParts } from "./graph-files.js";
+const creds = {
+    clientId: "app-1",
+    clientSecret: "secret",
+    tenantId: "tenant-1",
+};
+const ref = {
+    teamId: "team-1",
+    channelId: "19:abc@thread.tacv2",
+    messageId: "100",
+    rootId: "100",
+};
+/**
+ * Route fetch by URL: the token endpoint, the Graph message read, and the
+ * SharePoint download all hit different hosts/paths.
+ */
+function routeFetch(handlers) {
+    vi.stubGlobal("fetch", vi.fn(async (url) => {
+        if (url.includes("/oauth2/v2.0/token")) {
+            return {
+                ok: true,
+                status: 200,
+                json: async () => ({ access_token: "tok", expires_in: 3600 }),
+            };
+        }
+        if (url.includes("/messages/")) {
+            return {
+                ok: true,
+                status: 200,
+                json: async () => handlers.message,
+            };
+        }
+        // /shares/.../driveItem/content
+        const d = handlers.download ?? {};
+        return {
+            ok: d.ok ?? true,
+            status: d.status ?? 200,
+            arrayBuffer: async () => (d.body ?? new Uint8Array()).buffer,
+            text: async () => "",
+        };
+    }));
+}
+afterEach(() => vi.unstubAllGlobals());
+describe("buildChannelFileContentParts (Graph)", () => {
+    it("reads a channel message's reference attachment and downloads the CSV", async () => {
+        routeFetch({
+            message: {
+                attachments: [
+                    {
+                        contentType: "reference",
+                        contentUrl: "https://contoso.sharepoint.com/sites/team/Shared Documents/incidents.csv",
+                        name: "incidents.csv",
+                    },
+                ],
+            },
+            download: { body: new TextEncoder().encode("severity,count\nSev1,4") },
+        });
+        const { parts, notes } = await buildChannelFileContentParts(ref, creds);
+        expect(notes).toEqual([]);
+        expect(parts).toHaveLength(1);
+        const text = parts[0].text;
+        expect(text).toContain('Attached file "incidents.csv" (text/csv)');
+        expect(text).toContain("severity,count");
+    });
+    it("ignores non-file (mention/html) attachments", async () => {
+        routeFetch({
+            message: {
+                attachments: [
+                    { contentType: "messageReference", content: "{}" },
+                    { contentType: "reference" }, // no contentUrl
+                ],
+            },
+        });
+        const { parts, notes } = await buildChannelFileContentParts(ref, creds);
+        expect(parts).toEqual([]);
+        expect(notes).toEqual([]);
+    });
+    it("notes a download permission failure (so the caller can react)", async () => {
+        routeFetch({
+            message: {
+                attachments: [
+                    {
+                        contentType: "reference",
+                        contentUrl: "https://contoso.sharepoint.com/sites/team/x.csv",
+                        name: "x.csv",
+                    },
+                ],
+            },
+            download: { ok: false, status: 403 },
+        });
+        const { parts, notes } = await buildChannelFileContentParts(ref, creds);
+        expect(parts).toEqual([]);
+        expect(notes[0]).toContain("Files.Read.All");
+    });
+    it("notes when the channel-message read fails (e.g. RSC not granted)", async () => {
+        vi.stubGlobal("fetch", vi.fn(async (url) => {
+            if (url.includes("/oauth2/v2.0/token")) {
+                return {
+                    ok: true,
+                    json: async () => ({ access_token: "t", expires_in: 3600 }),
+                };
+            }
+            return {
+                ok: false,
+                status: 403,
+                text: async () => "forbidden",
+            };
+        }));
+        const { parts, notes } = await buildChannelFileContentParts(ref, creds);
+        expect(parts).toEqual([]);
+        expect(notes[0]).toContain("ChannelMessage.Read.Group");
+    });
+});