@gakr-gakr/msteams 0.1.0

package/src/oauth.token.ts

@@ -0,0 +1,162 @@
+import { readProviderJsonResponse } from "autobot/plugin-sdk/provider-http";
+import { fetchWithSsrFGuard } from "autobot/plugin-sdk/ssrf-runtime";
+import {
+  MSTEAMS_DEFAULT_DELEGATED_SCOPES,
+  MSTEAMS_DEFAULT_TOKEN_FETCH_TIMEOUT_MS,
+  MSTEAMS_OAUTH_REDIRECT_URI,
+  buildMSTeamsTokenEndpoint,
+  type MSTeamsDelegatedTokens,
+} from "./oauth.shared.js";
+
+/** Five-minute buffer subtracted from token expiry to avoid edge-case clock drift. */
+const EXPIRY_BUFFER_MS = 5 * 60 * 1000;
+
+type MSTeamsTokenResponse = {
+  access_token: string;
+  refresh_token?: string;
+  expires_in: number;
+  scope?: string;
+};
+
+function createMSTeamsTokenBody(params: {
+  clientId: string;
+  clientSecret: string;
+  grantType: string;
+  scopes: readonly string[];
+  values?: Record<string, string>;
+}): URLSearchParams {
+  const body = new URLSearchParams({
+    client_id: params.clientId,
+    client_secret: params.clientSecret,
+    grant_type: params.grantType,
+    scope: [...params.scopes].join(" "),
+  });
+
+  for (const [key, value] of Object.entries(params.values ?? {})) {
+    body.set(key, value);
+  }
+
+  return body;
+}
+
+async function fetchMSTeamsTokens(params: {
+  tokenUrl: string;
+  body: URLSearchParams;
+  auditContext: string;
+  failureLabel: string;
+}): Promise<MSTeamsTokenResponse> {
+  const currentFetch = globalThis.fetch;
+  const { response, release } = await fetchWithSsrFGuard({
+    url: params.tokenUrl,
+    fetchImpl: async (input, guardedInit) => await currentFetch(input, guardedInit),
+    init: {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8",
+        Accept: "application/json",
+      },
+      body: params.body,
+      signal: AbortSignal.timeout(MSTEAMS_DEFAULT_TOKEN_FETCH_TIMEOUT_MS),
+    },
+    auditContext: params.auditContext,
+  });
+
+  try {
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`MSTeams ${params.failureLabel} failed (${response.status}): ${errorText}`);
+    }
+    return await readProviderJsonResponse<MSTeamsTokenResponse>(
+      response,
+      `MSTeams ${params.failureLabel} failed`,
+    );
+  } finally {
+    await release();
+  }
+}
+
+async function requestMSTeamsDelegatedTokens(params: {
+  tenantId: string;
+  clientId: string;
+  clientSecret: string;
+  scopes?: readonly string[];
+  grantType: string;
+  values: Record<string, string>;
+  auditContext: string;
+  failureLabel: string;
+  resolveRefreshToken: (data: MSTeamsTokenResponse) => string;
+}): Promise<MSTeamsDelegatedTokens> {
+  const scopes = params.scopes ?? MSTEAMS_DEFAULT_DELEGATED_SCOPES;
+  const body = createMSTeamsTokenBody({
+    clientId: params.clientId,
+    clientSecret: params.clientSecret,
+    grantType: params.grantType,
+    scopes,
+    values: params.values,
+  });
+  const data = await fetchMSTeamsTokens({
+    tokenUrl: buildMSTeamsTokenEndpoint(params.tenantId),
+    body,
+    auditContext: params.auditContext,
+    failureLabel: params.failureLabel,
+  });
+
+  return {
+    accessToken: data.access_token,
+    refreshToken: params.resolveRefreshToken(data),
+    expiresAt: Date.now() + data.expires_in * 1000 - EXPIRY_BUFFER_MS,
+    scopes: data.scope ? data.scope.split(" ") : [...scopes],
+  };
+}
+
+export async function exchangeMSTeamsCodeForTokens(params: {
+  tenantId: string;
+  clientId: string;
+  clientSecret: string;
+  code: string;
+  verifier: string;
+  scopes?: readonly string[];
+}): Promise<MSTeamsDelegatedTokens> {
+  return await requestMSTeamsDelegatedTokens({
+    tenantId: params.tenantId,
+    clientId: params.clientId,
+    clientSecret: params.clientSecret,
+    grantType: "authorization_code",
+    scopes: params.scopes,
+    values: {
+      code: params.code,
+      redirect_uri: MSTEAMS_OAUTH_REDIRECT_URI,
+      code_verifier: params.verifier,
+    },
+    auditContext: "msteams-oauth-token-exchange",
+    failureLabel: "token exchange",
+    resolveRefreshToken: (data) => {
+      if (!data.refresh_token) {
+        throw new Error("No refresh token received from Azure AD. Please try again.");
+      }
+      return data.refresh_token;
+    },
+  });
+}
+
+export async function refreshMSTeamsDelegatedTokens(params: {
+  tenantId: string;
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+  scopes?: readonly string[];
+}): Promise<MSTeamsDelegatedTokens> {
+  return await requestMSTeamsDelegatedTokens({
+    tenantId: params.tenantId,
+    clientId: params.clientId,
+    clientSecret: params.clientSecret,
+    grantType: "refresh_token",
+    scopes: params.scopes,
+    values: {
+      refresh_token: params.refreshToken,
+    },
+    auditContext: "msteams-oauth-token-refresh",
+    failureLabel: "token refresh",
+    resolveRefreshToken: (data) => data.refresh_token ?? params.refreshToken,
+  });
+}

package/src/oauth.ts

@@ -0,0 +1,130 @@
+import {
+  buildMSTeamsAuthUrl,
+  generateOAuthState,
+  generatePkce,
+  parseCallbackInput,
+  shouldUseManualOAuthFlow,
+  waitForLocalCallback,
+} from "./oauth.flow.js";
+import {
+  MSTEAMS_DEFAULT_DELEGATED_SCOPES,
+  MSTEAMS_OAUTH_CALLBACK_PORT,
+  type MSTeamsDelegatedOAuthContext,
+  type MSTeamsDelegatedTokens,
+} from "./oauth.shared.js";
+import { exchangeMSTeamsCodeForTokens } from "./oauth.token.js";
+
+export type { MSTeamsDelegatedOAuthContext, MSTeamsDelegatedTokens };
+
+export async function loginMSTeamsDelegated(
+  ctx: MSTeamsDelegatedOAuthContext,
+  params: {
+    tenantId: string;
+    clientId: string;
+    clientSecret: string;
+    scopes?: readonly string[];
+  },
+): Promise<MSTeamsDelegatedTokens> {
+  const scopes = params.scopes ?? MSTEAMS_DEFAULT_DELEGATED_SCOPES;
+  const needsManual = shouldUseManualOAuthFlow(ctx.isRemote);
+
+  await ctx.note(
+    needsManual
+      ? [
+          "You are running in a remote/VPS environment.",
+          "A URL will be shown for you to open in your LOCAL browser.",
+          "After signing in, copy the redirect URL and paste it back here.",
+        ].join("\n")
+      : [
+          "Browser will open for Microsoft authentication.",
+          `Sign in to grant delegated permissions for MSTeams.`,
+          `The callback will be captured automatically on localhost:${MSTEAMS_OAUTH_CALLBACK_PORT}.`,
+        ].join("\n"),
+    "MSTeams Delegated OAuth",
+  );
+
+  const { verifier, challenge } = generatePkce();
+  const state = generateOAuthState();
+  const authUrl = buildMSTeamsAuthUrl({
+    tenantId: params.tenantId,
+    clientId: params.clientId,
+    challenge,
+    state,
+    scopes,
+  });
+
+  if (needsManual) {
+    return manualFlow(ctx, authUrl, state, verifier, params);
+  }
+
+  ctx.progress.update("Complete sign-in in browser...");
+  try {
+    await ctx.openUrl(authUrl);
+  } catch {
+    ctx.log(`\nOpen this URL in your browser:\n\n${authUrl}\n`);
+  }
+
+  try {
+    const { code } = await waitForLocalCallback({
+      expectedState: state,
+      timeoutMs: 5 * 60 * 1000,
+      onProgress: (msg) => ctx.progress.update(msg),
+    });
+    ctx.progress.update("Exchanging authorization code for tokens...");
+    return await exchangeMSTeamsCodeForTokens({
+      tenantId: params.tenantId,
+      clientId: params.clientId,
+      clientSecret: params.clientSecret,
+      code,
+      verifier,
+      scopes,
+    });
+  } catch (err) {
+    // EADDRINUSE or other listen errors: fall back to manual flow
+    if (
+      err instanceof Error &&
+      (err.message.includes("EADDRINUSE") ||
+        err.message.includes("port") ||
+        err.message.includes("listen"))
+    ) {
+      ctx.progress.update("Local callback server failed. Switching to manual mode...");
+      return manualFlow(ctx, authUrl, state, verifier, params, err);
+    }
+    throw err;
+  }
+}
+
+async function manualFlow(
+  ctx: MSTeamsDelegatedOAuthContext,
+  authUrl: string,
+  state: string,
+  verifier: string,
+  params: {
+    tenantId: string;
+    clientId: string;
+    clientSecret: string;
+    scopes?: readonly string[];
+  },
+  cause?: Error,
+): Promise<MSTeamsDelegatedTokens> {
+  ctx.progress.update("OAuth URL ready");
+  ctx.log(`\nOpen this URL in your LOCAL browser:\n\n${authUrl}\n`);
+  ctx.progress.update("Waiting for you to paste the callback URL...");
+  const callbackInput = await ctx.prompt("Paste the redirect URL here: ");
+  const parsed = parseCallbackInput(callbackInput, state);
+  if ("error" in parsed) {
+    throw new Error(parsed.error, cause ? { cause } : undefined);
+  }
+  if (parsed.state !== state) {
+    throw new Error("OAuth state mismatch - please try again", cause ? { cause } : undefined);
+  }
+  ctx.progress.update("Exchanging authorization code for tokens...");
+  return exchangeMSTeamsCodeForTokens({
+    tenantId: params.tenantId,
+    clientId: params.clientId,
+    clientSecret: params.clientSecret,
+    code: parsed.code,
+    verifier,
+    scopes: params.scopes,
+  });
+}

package/src/outbound.ts

@@ -0,0 +1,198 @@
+import {
+  attachChannelToResult,
+  createAttachedChannelResultAdapter,
+} from "autobot/plugin-sdk/channel-send-result";
+import { resolveOutboundSendDep } from "autobot/plugin-sdk/outbound-send-deps";
+import {
+  resolvePayloadMediaUrls,
+  resolveTextChunksWithFallback,
+  sendPayloadMediaSequence,
+} from "autobot/plugin-sdk/reply-payload";
+import { chunkTextForOutbound, type ChannelOutboundAdapter } from "../runtime-api.js";
+import { createMSTeamsPollStoreFs } from "./polls.js";
+import { buildMSTeamsPresentationCard, MSTEAMS_PRESENTATION_CAPABILITIES } from "./presentation.js";
+import { sendAdaptiveCardMSTeams, sendMessageMSTeams, sendPollMSTeams } from "./send.js";
+
+function asObjectRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+const MSTEAMS_TEXT_CHUNK_LIMIT = 4000;
+
+export const msteamsOutbound: ChannelOutboundAdapter = {
+  deliveryMode: "direct",
+  chunker: chunkTextForOutbound,
+  chunkerMode: "markdown",
+  textChunkLimit: MSTEAMS_TEXT_CHUNK_LIMIT,
+  pollMaxOptions: 12,
+  deliveryCapabilities: {
+    durableFinal: {
+      text: true,
+      media: true,
+      payload: true,
+      messageSendingHooks: true,
+    },
+  },
+  presentationCapabilities: MSTEAMS_PRESENTATION_CAPABILITIES,
+  renderPresentation: ({ payload, presentation }) => {
+    if (payload.mediaUrl || payload.mediaUrls?.length) {
+      return null;
+    }
+    const card = buildMSTeamsPresentationCard({
+      presentation,
+      text: payload.text,
+    });
+    const msteamsData = asObjectRecord(payload.channelData?.msteams) ?? {};
+    return {
+      ...payload,
+      channelData: {
+        ...payload.channelData,
+        msteams: {
+          ...msteamsData,
+          presentationCard: card,
+        },
+      },
+    };
+  },
+  sendPayload: async ({
+    cfg,
+    to,
+    text,
+    mediaUrl,
+    mediaLocalRoots,
+    mediaReadFile,
+    payload,
+    deps,
+  }) => {
+    const msteamsData = asObjectRecord(payload.channelData?.msteams);
+    const presentationCard = msteamsData?.presentationCard;
+    if (
+      presentationCard &&
+      typeof presentationCard === "object" &&
+      !Array.isArray(presentationCard)
+    ) {
+      const result = await sendAdaptiveCardMSTeams({
+        cfg,
+        to,
+        card: presentationCard as Record<string, unknown>,
+      });
+      return attachChannelToResult("msteams", result);
+    }
+    const mediaUrls = resolvePayloadMediaUrls({
+      ...payload,
+      mediaUrl: payload.mediaUrl ?? mediaUrl,
+    })
+      .map((url) => url.trim())
+      .filter(Boolean);
+    if (mediaUrls.length > 0) {
+      type SendFn = (
+        to: string,
+        text: string,
+        opts?: {
+          mediaUrl?: string;
+          mediaLocalRoots?: readonly string[];
+          mediaReadFile?: (filePath: string) => Promise<Buffer>;
+        },
+      ) => Promise<{ messageId: string; conversationId: string }>;
+      const send =
+        resolveOutboundSendDep<SendFn>(deps, "msteams") ??
+        ((to, text, opts) =>
+          sendMessageMSTeams({
+            cfg,
+            to,
+            text,
+            mediaUrl: opts?.mediaUrl,
+            mediaLocalRoots: opts?.mediaLocalRoots,
+            mediaReadFile: opts?.mediaReadFile,
+          }));
+      const result = await sendPayloadMediaSequence({
+        text,
+        mediaUrls,
+        send: async ({ text, mediaUrl }) =>
+          await send(to, text, { mediaUrl, mediaLocalRoots, mediaReadFile }),
+      });
+      if (result) {
+        return attachChannelToResult("msteams", result);
+      }
+    }
+    if (text.trim()) {
+      type SendFn = (
+        to: string,
+        text: string,
+      ) => Promise<{ messageId: string; conversationId: string }>;
+      const send =
+        resolveOutboundSendDep<SendFn>(deps, "msteams") ??
+        ((to, text) => sendMessageMSTeams({ cfg, to, text }));
+      const chunks = resolveTextChunksWithFallback(
+        text,
+        chunkTextForOutbound(text, MSTEAMS_TEXT_CHUNK_LIMIT),
+      );
+      let result: Awaited<ReturnType<SendFn>>;
+      for (const chunk of chunks) {
+        result = await send(to, chunk);
+      }
+      return attachChannelToResult("msteams", result!);
+    }
+    throw new Error("MS Teams payload send requires text, media, or a presentation card.");
+  },
+  ...createAttachedChannelResultAdapter({
+    channel: "msteams",
+    sendText: async ({ cfg, to, text, deps }) => {
+      type SendFn = (
+        to: string,
+        text: string,
+      ) => Promise<{ messageId: string; conversationId: string }>;
+      const send =
+        resolveOutboundSendDep<SendFn>(deps, "msteams") ??
+        ((to, text) => sendMessageMSTeams({ cfg, to, text }));
+      return await send(to, text);
+    },
+    sendMedia: async ({ cfg, to, text, mediaUrl, mediaLocalRoots, mediaReadFile, deps }) => {
+      type SendFn = (
+        to: string,
+        text: string,
+        opts?: {
+          mediaUrl?: string;
+          mediaLocalRoots?: readonly string[];
+          mediaReadFile?: (filePath: string) => Promise<Buffer>;
+        },
+      ) => Promise<{ messageId: string; conversationId: string }>;
+      const send =
+        resolveOutboundSendDep<SendFn>(deps, "msteams") ??
+        ((to, text, opts) =>
+          sendMessageMSTeams({
+            cfg,
+            to,
+            text,
+            mediaUrl: opts?.mediaUrl,
+            mediaLocalRoots: opts?.mediaLocalRoots,
+            mediaReadFile: opts?.mediaReadFile,
+          }));
+      return await send(to, text, { mediaUrl, mediaLocalRoots, mediaReadFile });
+    },
+    sendPoll: async ({ cfg, to, poll }) => {
+      const maxSelections = poll.maxSelections ?? 1;
+      const result = await sendPollMSTeams({
+        cfg,
+        to,
+        question: poll.question,
+        options: poll.options,
+        maxSelections,
+      });
+      const pollStore = createMSTeamsPollStoreFs();
+      await pollStore.createPoll({
+        id: result.pollId,
+        question: poll.question,
+        options: poll.options,
+        maxSelections,
+        createdAt: new Date().toISOString(),
+        conversationId: result.conversationId,
+        messageId: result.messageId,
+        votes: {},
+      });
+      return result;
+    },
+  }),
+};