@kodelyth/msteams 2026.5.39 → 2026.5.42

package/src/user-agent.test.ts

@@ -0,0 +1,121 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock the runtime before importing buildUserAgent
+const mockRuntime = {
+  version: "2026.3.19",
+};
+
+vi.mock("./runtime.js", () => ({
+  getMSTeamsRuntime: vi.fn(() => mockRuntime),
+}));
+
+vi.mock("../runtime-api.js", async (importOriginal) => {
+  const original = await importOriginal<typeof import("../runtime-api.js")>();
+  return {
+    ...original,
+    fetchWithSsrFGuard: async (params: { url: string; init?: RequestInit }) => ({
+      response: await globalThis.fetch(params.url, params.init),
+      finalUrl: params.url,
+      release: async () => undefined,
+    }),
+  };
+});
+
+import { fetchGraphJson } from "./graph.js";
+import { getMSTeamsRuntime } from "./runtime.js";
+import { buildUserAgent, ensureUserAgentHeader, resetUserAgentCache } from "./user-agent.js";
+
+function readFirstFetchInit(mockFetch: { mock: { calls: unknown[][] } }): {
+  headers: Record<string, string>;
+} {
+  const [call] = mockFetch.mock.calls;
+  if (!call) {
+    throw new Error("Expected Graph fetch call");
+  }
+  const [, init] = call;
+  if (
+    !init ||
+    typeof init !== "object" ||
+    !("headers" in init) ||
+    typeof init.headers !== "object" ||
+    init.headers === null
+  ) {
+    throw new Error("Expected Graph fetch init headers");
+  }
+  return init as { headers: Record<string, string> };
+}
+
+describe("buildUserAgent", () => {
+  beforeEach(() => {
+    resetUserAgentCache();
+    vi.mocked(getMSTeamsRuntime).mockReturnValue(mockRuntime as never);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("returns teams.ts[apps]/<sdk> Klaw/<version> format", () => {
+    const ua = buildUserAgent();
+    expect(ua).toMatch(/^teams\.ts\[apps\]\/.+ Klaw\/2026\.3\.19$/);
+  });
+
+  it("reflects the runtime version", () => {
+    vi.mocked(getMSTeamsRuntime).mockReturnValue({ version: "1.2.3" } as never);
+    const ua = buildUserAgent();
+    expect(ua).toMatch(/Klaw\/1\.2\.3$/);
+  });
+
+  it("returns Klaw/unknown when runtime is not initialized", () => {
+    vi.mocked(getMSTeamsRuntime).mockImplementation(() => {
+      throw new Error("MSTeams runtime not initialized");
+    });
+    const ua = buildUserAgent();
+    expect(ua).toMatch(/Klaw\/unknown$/);
+    // SDK version should still be present
+    expect(ua).toMatch(/^teams\.ts\[apps\]\//);
+  });
+
+  it("sends the generated User-Agent in Graph requests by default", async () => {
+    const mockFetch = vi.fn().mockResolvedValueOnce(
+      new Response(JSON.stringify({ value: [] }), {
+        headers: { "content-type": "application/json" },
+      }),
+    );
+    vi.stubGlobal("fetch", mockFetch);
+
+    await fetchGraphJson({ token: "test-token", path: "/groups" });
+
+    expect(mockFetch).toHaveBeenCalledOnce();
+    const init = readFirstFetchInit(mockFetch);
+    expect(init.headers["User-Agent"]).toMatch(/^teams\.ts\[apps\]\/.+ Klaw\/2026\.3\.19$/);
+    expect(init.headers).toHaveProperty("Authorization", "Bearer test-token");
+  });
+
+  it("lets caller headers override the default Graph User-Agent", async () => {
+    const mockFetch = vi.fn().mockResolvedValueOnce(
+      new Response(JSON.stringify({ value: [] }), {
+        headers: { "content-type": "application/json" },
+      }),
+    );
+    vi.stubGlobal("fetch", mockFetch);
+
+    await fetchGraphJson({
+      token: "test-token",
+      path: "/groups",
+      headers: { "User-Agent": "custom-agent/1.0" },
+    });
+
+    const init = readFirstFetchInit(mockFetch);
+    expect(init.headers["User-Agent"]).toBe("custom-agent/1.0");
+  });
+
+  it("adds the generated User-Agent to Headers instances without overwriting callers", () => {
+    const generated = ensureUserAgentHeader();
+    expect(generated.get("User-Agent")).toMatch(/^teams\.ts\[apps\]\/.+ Klaw\/2026\.3\.19$/);
+
+    const custom = ensureUserAgentHeader({ "User-Agent": "custom-agent/2.0" });
+    expect(custom.get("User-Agent")).toBe("custom-agent/2.0");
+  });
+});

package/src/user-agent.ts

@@ -0,0 +1,53 @@
+import { createRequire } from "node:module";
+import { getMSTeamsRuntime } from "./runtime.js";
+
+let cachedUserAgent: string | undefined;
+
+function resolveTeamsSdkVersion(): string {
+  try {
+    const require = createRequire(import.meta.url);
+    const pkg = require("@microsoft/teams.apps/package.json") as { version?: string };
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+function resolveKlawVersion(): string {
+  try {
+    return getMSTeamsRuntime().version;
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Build a combined User-Agent string that preserves the Teams SDK identity
+ * and appends the Klaw version.
+ *
+ * Format: "teams.ts[apps]/<sdk-version> Klaw/<klaw-version>"
+ * Example: "teams.ts[apps]/2.0.5 Klaw/2026.3.22"
+ *
+ * This lets the Teams backend track SDK usage while also identifying the
+ * host application.
+ */
+/** Reset the cached User-Agent (for testing). */
+export function resetUserAgentCache(): void {
+  cachedUserAgent = undefined;
+}
+
+export function buildUserAgent(): string {
+  if (cachedUserAgent) {
+    return cachedUserAgent;
+  }
+  cachedUserAgent = `teams.ts[apps]/${resolveTeamsSdkVersion()} Klaw/${resolveKlawVersion()}`;
+  return cachedUserAgent;
+}
+
+export function ensureUserAgentHeader(headers?: HeadersInit): Headers {
+  const nextHeaders = new Headers(headers);
+  if (!nextHeaders.has("User-Agent")) {
+    nextHeaders.set("User-Agent", buildUserAgent());
+  }
+  return nextHeaders;
+}

package/src/webhook-timeouts.ts

@@ -0,0 +1,27 @@
+import type { Server } from "node:http";
+
+const MSTEAMS_WEBHOOK_INACTIVITY_TIMEOUT_MS = 30_000;
+const MSTEAMS_WEBHOOK_REQUEST_TIMEOUT_MS = 30_000;
+const MSTEAMS_WEBHOOK_HEADERS_TIMEOUT_MS = 15_000;
+
+type ApplyMSTeamsWebhookTimeoutsOpts = {
+  inactivityTimeoutMs?: number;
+  requestTimeoutMs?: number;
+  headersTimeoutMs?: number;
+};
+
+export function applyMSTeamsWebhookTimeouts(
+  httpServer: Server,
+  opts?: ApplyMSTeamsWebhookTimeoutsOpts,
+): void {
+  const inactivityTimeoutMs = opts?.inactivityTimeoutMs ?? MSTEAMS_WEBHOOK_INACTIVITY_TIMEOUT_MS;
+  const requestTimeoutMs = opts?.requestTimeoutMs ?? MSTEAMS_WEBHOOK_REQUEST_TIMEOUT_MS;
+  const headersTimeoutMs = Math.min(
+    opts?.headersTimeoutMs ?? MSTEAMS_WEBHOOK_HEADERS_TIMEOUT_MS,
+    requestTimeoutMs,
+  );
+
+  httpServer.setTimeout(inactivityTimeoutMs);
+  httpServer.requestTimeout = requestTimeoutMs;
+  httpServer.headersTimeout = headersTimeoutMs;
+}

package/src/welcome-card.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from "vitest";
+import { buildMSTeamsPresentationCard } from "./presentation.js";
+import { buildGroupWelcomeText, buildWelcomeCard } from "./welcome-card.js";
+
+describe("buildMSTeamsPresentationCard", () => {
+  it("preserves message text when rendering presentation controls", () => {
+    expect(
+      buildMSTeamsPresentationCard({
+        text: "Deploy finished",
+        presentation: {
+          blocks: [
+            {
+              type: "buttons",
+              buttons: [{ label: "Open", value: "open" }],
+            },
+          ],
+        },
+      }),
+    ).toEqual({
+      type: "AdaptiveCard",
+      version: "1.4",
+      body: [{ type: "TextBlock", text: "Deploy finished", wrap: true }],
+      actions: [{ type: "Action.Submit", title: "Open", data: { value: "open", label: "Open" } }],
+    });
+  });
+
+  it("renders web app button links as open-url actions", () => {
+    expect(
+      buildMSTeamsPresentationCard({
+        presentation: {
+          blocks: [
+            {
+              type: "buttons",
+              buttons: [
+                { label: "Open app", webApp: { url: "https://example.com/app" } },
+                { label: "Legacy app", web_app: { url: "https://example.com/legacy" } },
+              ],
+            },
+          ],
+        },
+      }),
+    ).toMatchObject({
+      actions: [
+        { type: "Action.OpenUrl", title: "Open app", url: "https://example.com/app" },
+        { type: "Action.OpenUrl", title: "Legacy app", url: "https://example.com/legacy" },
+      ],
+    });
+  });
+});
+
+describe("buildWelcomeCard", () => {
+  it("builds card with default prompt starters", () => {
+    const card = buildWelcomeCard();
+    expect(card.type).toBe("AdaptiveCard");
+    expect(card.version).toBe("1.5");
+
+    const body = card.body as Array<{ text: string }>;
+    expect(body[0]?.text).toContain("Klaw");
+
+    const actions = card.actions as Array<{ title: string; data: unknown }>;
+    expect(actions.length).toBe(3);
+    expect(actions[0]?.title).toBe("What can you do?");
+  });
+
+  it("uses custom bot name", () => {
+    const card = buildWelcomeCard({ botName: "TestBot" });
+    const body = card.body as Array<{ text: string }>;
+    expect(body[0]?.text).toContain("TestBot");
+  });
+
+  it("uses custom prompt starters", () => {
+    const card = buildWelcomeCard({
+      promptStarters: ["Do X", "Do Y"],
+    });
+    const actions = card.actions as Array<{ title: string; data: unknown }>;
+    expect(actions.length).toBe(2);
+    expect(actions[0]?.title).toBe("Do X");
+    expect(actions[1]?.title).toBe("Do Y");
+
+    // Verify imBack data
+    const data = actions[0]?.data as { msteams: { type: string; value: string } };
+    expect(data.msteams.type).toBe("imBack");
+    expect(data.msteams.value).toBe("Do X");
+  });
+
+  it("falls back to defaults when promptStarters is empty", () => {
+    const card = buildWelcomeCard({ promptStarters: [] });
+    const actions = card.actions as Array<{ title: string }>;
+    expect(actions.length).toBe(3);
+  });
+});
+
+describe("buildGroupWelcomeText", () => {
+  it("includes bot name", () => {
+    const text = buildGroupWelcomeText("MyBot");
+    expect(text).toContain("MyBot");
+    expect(text).toContain("@MyBot");
+  });
+
+  it("defaults to Klaw", () => {
+    const text = buildGroupWelcomeText();
+    expect(text).toContain("Klaw");
+  });
+});

package/src/welcome-card.ts

@@ -0,0 +1,57 @@
+/**
+ * Builds an Adaptive Card for welcoming users when the bot is added to a conversation.
+ */
+
+const DEFAULT_PROMPT_STARTERS = [
+  "What can you do?",
+  "Summarize my last meeting",
+  "Help me draft an email",
+];
+
+type WelcomeCardOptions = {
+  /** Bot display name. Falls back to "Klaw". */
+  botName?: string;
+  /** Custom prompt starters. Falls back to defaults. */
+  promptStarters?: string[];
+};
+
+/**
+ * Build a welcome Adaptive Card for 1:1 personal chats.
+ */
+export function buildWelcomeCard(options?: WelcomeCardOptions): Record<string, unknown> {
+  const botName = options?.botName || "Klaw";
+  const starters = options?.promptStarters?.length
+    ? options.promptStarters
+    : DEFAULT_PROMPT_STARTERS;
+
+  return {
+    type: "AdaptiveCard",
+    version: "1.5",
+    body: [
+      {
+        type: "TextBlock",
+        text: `Hi! I'm ${botName}.`,
+        weight: "bolder",
+        size: "medium",
+      },
+      {
+        type: "TextBlock",
+        text: "I can help you with questions, tasks, and more. Here are some things to try:",
+        wrap: true,
+      },
+    ],
+    actions: starters.map((label) => ({
+      type: "Action.Submit",
+      title: label,
+      data: { msteams: { type: "imBack", value: label } },
+    })),
+  };
+}
+
+/**
+ * Build a brief welcome message for group chats (when the bot is @mentioned).
+ */
+export function buildGroupWelcomeText(botName?: string): string {
+  const name = botName || "Klaw";
+  return `Hi! I'm ${name}. Mention me with @${name} to get started.`;
+}

package/test-api.ts

@@ -0,0 +1 @@
+export { msteamsPlugin } from "./src/channel.js";

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.package-boundary.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["./*.ts", "./src/**/*.ts"],
+  "exclude": [
+    "./**/*.test.ts",
+    "./dist/**",
+    "./node_modules/**",
+    "./src/test-support/**",
+    "./src/**/*test-helpers.ts",
+    "./src/**/*test-harness.ts",
+    "./src/**/*test-support.ts"
+  ]
+}

package/api.js

@@ -1,7 +0,0 @@
-export * from "../../../dist/extensions/msteams/api.js";
-import * as module from "../../../dist/extensions/msteams/api.js";
-let defaultExport = "default" in module ? module.default : module;
-for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
-  defaultExport = defaultExport.default;
-}
-export { defaultExport as default };

package/channel-config-api.js

@@ -1,7 +0,0 @@
-export * from "../../../dist/extensions/msteams/channel-config-api.js";
-import * as module from "../../../dist/extensions/msteams/channel-config-api.js";
-let defaultExport = "default" in module ? module.default : module;
-for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
-  defaultExport = defaultExport.default;
-}
-export { defaultExport as default };

package/channel-plugin-api.js

@@ -1,7 +0,0 @@
-export * from "../../../dist/extensions/msteams/channel-plugin-api.js";
-import * as module from "../../../dist/extensions/msteams/channel-plugin-api.js";
-let defaultExport = "default" in module ? module.default : module;
-for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
-  defaultExport = defaultExport.default;
-}
-export { defaultExport as default };

package/contract-api.js

@@ -1,7 +0,0 @@
-export * from "../../../dist/extensions/msteams/contract-api.js";
-import * as module from "../../../dist/extensions/msteams/contract-api.js";
-let defaultExport = "default" in module ? module.default : module;
-for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
-  defaultExport = defaultExport.default;
-}
-export { defaultExport as default };

package/index.js

@@ -1,7 +0,0 @@
-export * from "../../../dist/extensions/msteams/index.js";
-import defaultModule from "../../../dist/extensions/msteams/index.js";
-let defaultExport = defaultModule;
-for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
-  defaultExport = defaultExport.default;
-}
-export { defaultExport as default };

package/runtime-api.js

@@ -1,7 +0,0 @@
-export * from "../../../dist/extensions/msteams/runtime-api.js";
-import * as module from "../../../dist/extensions/msteams/runtime-api.js";
-let defaultExport = "default" in module ? module.default : module;
-for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
-  defaultExport = defaultExport.default;
-}
-export { defaultExport as default };

package/secret-contract-api.js

@@ -1,7 +0,0 @@
-export * from "../../../dist/extensions/msteams/secret-contract-api.js";
-import * as module from "../../../dist/extensions/msteams/secret-contract-api.js";
-let defaultExport = "default" in module ? module.default : module;
-for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
-  defaultExport = defaultExport.default;
-}
-export { defaultExport as default };

package/setup-entry.js

@@ -1,7 +0,0 @@
-export * from "../../../dist/extensions/msteams/setup-entry.js";
-import defaultModule from "../../../dist/extensions/msteams/setup-entry.js";
-let defaultExport = defaultModule;
-for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
-  defaultExport = defaultExport.default;
-}
-export { defaultExport as default };

package/setup-plugin-api.js

@@ -1,7 +0,0 @@
-export * from "../../../dist/extensions/msteams/setup-plugin-api.js";
-import * as module from "../../../dist/extensions/msteams/setup-plugin-api.js";
-let defaultExport = "default" in module ? module.default : module;
-for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
-  defaultExport = defaultExport.default;
-}
-export { defaultExport as default };

package/test-api.js

@@ -1,7 +0,0 @@
-export * from "../../../dist/extensions/msteams/test-api.js";
-import * as module from "../../../dist/extensions/msteams/test-api.js";
-let defaultExport = "default" in module ? module.default : module;
-for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
-  defaultExport = defaultExport.default;
-}
-export { defaultExport as default };