@gakr-gakr/msteams 0.1.0

package/src/graph.ts

@@ -0,0 +1,308 @@
+import { readProviderJsonResponse } from "autobot/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.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";

package/src/media-helpers.ts

@@ -0,0 +1,105 @@
+/**
+ * MIME type detection and filename extraction for MSTeams media attachments.
+ */
+
+import path from "node:path";
+import {
+  detectMime,
+  extensionForMime,
+  extractOriginalFilename,
+  getFileExtension,
+} from "../runtime-api.js";
+
+/**
+ * Detect MIME type from URL extension or data URL.
+ * Uses shared MIME detection for consistency with core handling.
+ */
+export async function getMimeType(url: string): Promise<string> {
+  // Handle data URLs: data:image/png;base64,...
+  if (url.startsWith("data:")) {
+    const match = url.match(/^data:([^;,]+)/);
+    if (match?.[1]) {
+      return match[1];
+    }
+  }
+
+  // Use shared MIME detection (extension-based for URLs)
+  const detected = await detectMime({ filePath: url });
+  return detected ?? "application/octet-stream";
+}
+
+/**
+ * Extract filename from URL or local path.
+ * For local paths, extracts original filename if stored with embedded name pattern.
+ * Falls back to deriving the extension from MIME type when no extension present.
+ */
+export async function extractFilename(url: string): Promise<string> {
+  // Handle data URLs: derive extension from MIME
+  if (url.startsWith("data:")) {
+    const mime = await getMimeType(url);
+    const ext = extensionForMime(mime) ?? ".bin";
+    const prefix = mime.startsWith("image/") ? "image" : "file";
+    return `${prefix}${ext}`;
+  }
+
+  // Try to extract from URL pathname
+  try {
+    const pathname = new URL(url).pathname;
+    const basename = path.basename(pathname);
+    const existingExt = getFileExtension(pathname);
+    if (basename && existingExt) {
+      return basename;
+    }
+    // No extension in URL, derive from MIME
+    const mime = await getMimeType(url);
+    const ext = extensionForMime(mime) ?? ".bin";
+    const prefix = mime.startsWith("image/") ? "image" : "file";
+    return basename ? `${basename}${ext}` : `${prefix}${ext}`;
+  } catch {
+    // Local paths - use extractOriginalFilename to extract embedded original name
+    return extractOriginalFilename(url);
+  }
+}
+
+/**
+ * Check if a URL refers to a local file path.
+ */
+export function isLocalPath(url: string): boolean {
+  if (url.startsWith("file://") || url.startsWith("/") || url.startsWith("~")) {
+    return true;
+  }
+
+  // Windows rooted path on current drive (e.g. \tmp\file.txt)
+  if (url.startsWith("\\") && !url.startsWith("\\\\")) {
+    return true;
+  }
+
+  // Windows drive-letter absolute path (e.g. C:\foo\bar.txt or C:/foo/bar.txt)
+  if (/^[a-zA-Z]:[\\/]/.test(url)) {
+    return true;
+  }
+
+  // Windows UNC path (e.g. \\server\share\file.txt)
+  if (url.startsWith("\\\\")) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Extract the message ID from a Bot Framework response.
+ */
+export function extractMessageId(response: unknown): string | null {
+  if (!response || typeof response !== "object") {
+    return null;
+  }
+  if (!("id" in response)) {
+    return null;
+  }
+  const { id } = response as { id?: unknown };
+  if (typeof id !== "string" || !id) {
+    return null;
+  }
+  return id;
+}

package/src/mentions.ts

@@ -0,0 +1,114 @@
+/**
+ * MS Teams mention handling utilities.
+ *
+ * Mentions in Teams require:
+ * 1. Text containing <at>Name</at> tags
+ * 2. entities array with mention metadata
+ */
+
+type MentionEntity = {
+  type: "mention";
+  text: string;
+  mentioned: {
+    id: string;
+    name: string;
+  };
+};
+
+type MentionInfo = {
+  /** User/bot ID (e.g., "28:xxx" or AAD object ID) */
+  id: string;
+  /** Display name */
+  name: string;
+};
+
+/**
+ * Check whether an ID looks like a valid Teams user/bot identifier.
+ * Accepts:
+ * - Bot Framework IDs: "28:xxx..." / "29:xxx..." / "8:orgid:..."
+ * - AAD object IDs (UUIDs): "d5318c29-33ac-4e6b-bd42-57b8b793908f"
+ *
+ * Keep this permissive enough for real Teams IDs while still rejecting
+ * documentation placeholders like `@[表示名](ユーザーID)`.
+ */
+const TEAMS_BOT_ID_PATTERN = /^\d+:[a-z0-9._=-]+(?::[a-z0-9._=-]+)*$/i;
+const AAD_OBJECT_ID_PATTERN = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+
+function isValidTeamsId(id: string): boolean {
+  return TEAMS_BOT_ID_PATTERN.test(id) || AAD_OBJECT_ID_PATTERN.test(id);
+}
+
+/**
+ * Parse mentions from text in the format @[Name](id).
+ * Example: "Hello @[John Doe](28:xxx-yyy-zzz)!"
+ *
+ * Only matches where the id looks like a real Teams user/bot ID are treated
+ * as mentions. This avoids false positives from documentation or code samples
+ * embedded in the message (e.g. `@[表示名](ユーザーID)` in backticks).
+ *
+ * Returns both the formatted text with <at> tags and the entities array.
+ */
+export function parseMentions(text: string): {
+  text: string;
+  entities: MentionEntity[];
+} {
+  const mentionPattern = /@\[([^\]]+)\]\(([^)]+)\)/g;
+  const entities: MentionEntity[] = [];
+
+  // Replace @[Name](id) with <at>Name</at> only for valid Teams IDs
+  const formattedText = text.replace(mentionPattern, (match, name, id) => {
+    const trimmedId = id.trim();
+
+    // Skip matches where the id doesn't look like a real Teams identifier
+    if (!isValidTeamsId(trimmedId)) {
+      return match;
+    }
+
+    const trimmedName = name.trim();
+    const mentionTag = `<at>${trimmedName}</at>`;
+    entities.push({
+      type: "mention",
+      text: mentionTag,
+      mentioned: {
+        id: trimmedId,
+        name: trimmedName,
+      },
+    });
+    return mentionTag;
+  });
+
+  return {
+    text: formattedText,
+    entities,
+  };
+}
+
+/**
+ * Build mention entities array from a list of mentions.
+ * Use this when you already have the mention info and formatted text.
+ */
+export function buildMentionEntities(mentions: MentionInfo[]): MentionEntity[] {
+  return mentions.map((mention) => ({
+    type: "mention",
+    text: `<at>${mention.name}</at>`,
+    mentioned: {
+      id: mention.id,
+      name: mention.name,
+    },
+  }));
+}
+
+/**
+ * Format text with mentions using <at> tags.
+ * This is a convenience function when you want to manually format mentions.
+ */
+export function formatMentionText(text: string, mentions: MentionInfo[]): string {
+  let formatted = text;
+  for (const mention of mentions) {
+    // Replace @Name or @name with <at>Name</at>
+    const escapedName = mention.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const namePattern = new RegExp(`@${escapedName}`, "gi");
+    formatted = formatted.replace(namePattern, `<at>${mention.name}</at>`);
+  }
+  return formatted;
+}