@vellumai/assistant 0.5.14 → 0.5.16

package/src/messaging/providers/outlook/adapter.ts

@@ -0,0 +1,193 @@
+/**
+ * Outlook messaging provider adapter.
+ *
+ * Maps Microsoft Graph API responses to the platform-agnostic messaging types
+ * and implements the MessagingProvider interface.
+ */
+
+import type { OAuthConnection } from "../../../oauth/connection.js";
+import type { MessagingProvider } from "../../provider.js";
+import type {
+  ConnectionInfo,
+  Conversation,
+  HistoryOptions,
+  ListOptions,
+  Message,
+  SearchOptions,
+  SearchResult,
+  SendOptions,
+  SendResult,
+} from "../../provider-types.js";
+import * as outlook from "./client.js";
+import type { OutlookMessage } from "./types.js";
+
+function requireConnection(
+  connection: OAuthConnection | undefined,
+): OAuthConnection {
+  if (!connection) {
+    throw new Error(
+      "Outlook requires an OAuth connection — is the account connected?",
+    );
+  }
+  return connection;
+}
+
+function mapOutlookMessage(msg: OutlookMessage): Message {
+  const senderEmail = msg.from?.emailAddress?.address ?? "";
+  const senderName = msg.from?.emailAddress?.name || senderEmail || "Unknown";
+
+  return {
+    id: msg.id,
+    conversationId: msg.conversationId,
+    sender: {
+      id: senderEmail,
+      name: senderName,
+      email: senderEmail,
+    },
+    text: msg.body.contentType === "text" ? msg.body.content : msg.bodyPreview,
+    timestamp: new Date(msg.receivedDateTime).getTime(),
+    threadId: msg.conversationId,
+    platform: "outlook",
+    hasAttachments: msg.hasAttachments ?? false,
+    metadata: {
+      subject: msg.subject,
+      categories: msg.categories,
+      isRead: msg.isRead,
+      parentFolderId: msg.parentFolderId,
+    },
+  };
+}
+
+const MESSAGE_SELECT_FIELDS =
+  "id,conversationId,subject,bodyPreview,body,from,toRecipients,receivedDateTime,isRead,hasAttachments,parentFolderId,categories,flag";
+
+export const outlookMessagingProvider: MessagingProvider = {
+  id: "outlook",
+  displayName: "Outlook",
+  credentialService: "outlook",
+  capabilities: new Set(["threads", "folders"]),
+
+  async testConnection(connection?: OAuthConnection): Promise<ConnectionInfo> {
+    const conn = requireConnection(connection);
+    const profile = await outlook.getProfile(conn);
+    return {
+      connected: true,
+      user: profile.mail || profile.userPrincipalName,
+      platform: "outlook",
+    };
+  },
+
+  async listConversations(
+    connection: OAuthConnection | undefined,
+    _options?: ListOptions,
+  ): Promise<Conversation[]> {
+    const conn = requireConnection(connection);
+    const folders = await outlook.listMailFolders(conn);
+    return folders.map((folder) => ({
+      id: folder.id,
+      name: folder.displayName,
+      type: "inbox" as const,
+      platform: "outlook",
+      unreadCount: folder.unreadItemCount ?? 0,
+      lastActivityAt: Date.now(),
+      metadata: {
+        totalItemCount: folder.totalItemCount,
+        childFolderCount: folder.childFolderCount,
+      },
+    }));
+  },
+
+  async getHistory(
+    connection: OAuthConnection | undefined,
+    conversationId: string,
+    options?: HistoryOptions,
+  ): Promise<Message[]> {
+    const conn = requireConnection(connection);
+    const result = await outlook.listMessages(conn, {
+      folderId: conversationId,
+      top: options?.limit ?? 50,
+      orderby: "receivedDateTime desc",
+      select: MESSAGE_SELECT_FIELDS,
+    });
+    return (result.value ?? []).map(mapOutlookMessage);
+  },
+
+  async search(
+    connection: OAuthConnection | undefined,
+    query: string,
+    options?: SearchOptions,
+  ): Promise<SearchResult> {
+    const conn = requireConnection(connection);
+    const result = await outlook.searchMessages(conn, query, {
+      top: options?.count ?? 20,
+    });
+    const messages = result.value ?? [];
+    return {
+      total: result["@odata.count"] ?? messages.length,
+      messages: messages.map(mapOutlookMessage),
+      hasMore: !!result["@odata.nextLink"],
+    };
+  },
+
+  async sendMessage(
+    connection: OAuthConnection | undefined,
+    conversationId: string,
+    text: string,
+    options?: SendOptions,
+  ): Promise<SendResult> {
+    const conn = requireConnection(connection);
+
+    if (options?.inReplyTo) {
+      await outlook.replyToMessage(conn, options.inReplyTo, text);
+      return {
+        id: "",
+        timestamp: Date.now(),
+        conversationId,
+        threadId: options?.threadId,
+      };
+    }
+
+    await outlook.sendMessage(conn, {
+      message: {
+        subject: options?.subject ?? "",
+        body: { contentType: "text", content: text },
+        toRecipients: [{ emailAddress: { address: conversationId } }],
+      },
+    });
+
+    // Microsoft Graph's sendMail returns 202 with no body
+    return {
+      id: "",
+      timestamp: Date.now(),
+      conversationId,
+      threadId: options?.threadId,
+    };
+  },
+
+  async getThreadReplies(
+    connection: OAuthConnection | undefined,
+    _conversationId: string,
+    threadId: string,
+    options?: HistoryOptions,
+  ): Promise<Message[]> {
+    const conn = requireConnection(connection);
+    const result = await outlook.listMessages(conn, {
+      filter: `conversationId eq '${threadId.replace(/'/g, "''")}'`,
+      top: options?.limit ?? 50,
+      orderby: "receivedDateTime asc",
+      select: MESSAGE_SELECT_FIELDS,
+    });
+    return (result.value ?? []).map(mapOutlookMessage);
+  },
+
+  async markRead(
+    connection: OAuthConnection | undefined,
+    _conversationId: string,
+    messageId?: string,
+  ): Promise<void> {
+    const conn = requireConnection(connection);
+    if (messageId) {
+      await outlook.markMessageRead(conn, messageId);
+    }
+  },
+};

package/src/messaging/providers/outlook/client.ts

@@ -0,0 +1,311 @@
+import type {
+  OAuthConnection,
+  OAuthConnectionResponse,
+} from "../../../oauth/connection.js";
+import type {
+  OutlookMailFolder,
+  OutlookMailFolderListResponse,
+  OutlookMessage,
+  OutlookMessageListResponse,
+  OutlookSendMessagePayload,
+  OutlookUserProfile,
+} from "./types.js";
+
+export class OutlookApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly statusText: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "OutlookApiError";
+  }
+}
+
+const MAX_RETRIES = 3;
+const INITIAL_BACKOFF_MS = 1000;
+
+function isRetryable(status: number): boolean {
+  return status === 429 || (status >= 500 && status < 600);
+}
+
+const IDEMPOTENT_METHODS = new Set([
+  "GET",
+  "HEAD",
+  "PUT",
+  "DELETE",
+  "OPTIONS",
+  "PATCH",
+]);
+
+function isIdempotent(method: string): boolean {
+  return IDEMPOTENT_METHODS.has(method.toUpperCase());
+}
+
+/**
+ * Make an authenticated request to the Microsoft Graph API with retry logic.
+ *
+ * The OAuth provider's baseUrl is `https://graph.microsoft.com`, so all paths
+ * must include the full API version and resource prefix (e.g. `/v1.0/me/messages`).
+ */
+async function request<T>(
+  connection: OAuthConnection,
+  path: string,
+  options?: RequestInit,
+  query?: Record<string, string | string[]>,
+): Promise<T> {
+  const method = (options?.method ?? "GET").toUpperCase();
+  const canRetry = isIdempotent(method);
+
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    let resp: OAuthConnectionResponse;
+    try {
+      const extraHeaders =
+        options?.headers &&
+        typeof options.headers === "object" &&
+        !Array.isArray(options.headers)
+          ? (options.headers as Record<string, string>)
+          : {};
+      resp = await connection.request({
+        method,
+        path,
+        query,
+        headers: {
+          "Content-Type": "application/json",
+          ...extraHeaders,
+        },
+        body: options?.body ? JSON.parse(options.body as string) : undefined,
+      });
+    } catch (err) {
+      // Network-level errors from connection.request() are not retryable
+      throw err;
+    }
+
+    if (resp.status < 200 || resp.status >= 300) {
+      if (canRetry && isRetryable(resp.status) && attempt < MAX_RETRIES) {
+        const retryAfter =
+          resp.headers["retry-after"] ?? resp.headers["Retry-After"];
+        const delayMs = retryAfter
+          ? parseInt(retryAfter, 10) * 1000
+          : INITIAL_BACKOFF_MS * Math.pow(2, attempt);
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+        continue;
+      }
+      const bodyStr =
+        typeof resp.body === "string"
+          ? resp.body
+          : JSON.stringify(resp.body ?? "");
+      throw new OutlookApiError(
+        resp.status,
+        "",
+        `Microsoft Graph API ${resp.status}: ${bodyStr}`,
+      );
+    }
+
+    // Success
+    if (resp.status === 204 || resp.body === undefined) {
+      return undefined as T;
+    }
+    return resp.body as T;
+  }
+
+  throw new Error(
+    "Unreachable: retry loop exited without returning or throwing",
+  );
+}
+
+/** Get the authenticated user's profile. */
+export async function getProfile(
+  connection: OAuthConnection,
+): Promise<OutlookUserProfile> {
+  return request<OutlookUserProfile>(connection, "/v1.0/me");
+}
+
+/** List messages, optionally within a specific folder. */
+export async function listMessages(
+  connection: OAuthConnection,
+  options?: {
+    folderId?: string;
+    top?: number;
+    skip?: number;
+    filter?: string;
+    orderby?: string;
+    select?: string;
+  },
+): Promise<OutlookMessageListResponse> {
+  const path = options?.folderId
+    ? `/v1.0/me/mailFolders/${encodeURIComponent(options.folderId)}/messages`
+    : "/v1.0/me/messages";
+
+  const query: Record<string, string> = {};
+  if (options?.top !== undefined) query["$top"] = String(options.top);
+  if (options?.skip !== undefined) query["$skip"] = String(options.skip);
+  if (options?.filter) query["$filter"] = options.filter;
+  if (options?.orderby) query["$orderby"] = options.orderby;
+  if (options?.select) query["$select"] = options.select;
+
+  return request<OutlookMessageListResponse>(
+    connection,
+    path,
+    undefined,
+    Object.keys(query).length > 0 ? query : undefined,
+  );
+}
+
+/** Get a single message by ID. */
+export async function getMessage(
+  connection: OAuthConnection,
+  messageId: string,
+  select?: string,
+): Promise<OutlookMessage> {
+  const query: Record<string, string> = {};
+  if (select) query["$select"] = select;
+
+  return request<OutlookMessage>(
+    connection,
+    `/v1.0/me/messages/${encodeURIComponent(messageId)}`,
+    undefined,
+    Object.keys(query).length > 0 ? query : undefined,
+  );
+}
+
+/** Search messages using Microsoft Graph KQL syntax. */
+export async function searchMessages(
+  connection: OAuthConnection,
+  searchQuery: string,
+  options?: {
+    top?: number;
+    skip?: number;
+  },
+): Promise<OutlookMessageListResponse> {
+  const query: Record<string, string> = {
+    $search: `"${searchQuery.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`,
+    $count: "true",
+  };
+  if (options?.top !== undefined) query["$top"] = String(options.top);
+  if (options?.skip !== undefined) query["$skip"] = String(options.skip);
+
+  return request<OutlookMessageListResponse>(
+    connection,
+    "/v1.0/me/messages",
+    {
+      headers: {
+        ConsistencyLevel: "eventual",
+      },
+    },
+    query,
+  );
+}
+
+/** Send a new message. */
+export async function sendMessage(
+  connection: OAuthConnection,
+  message: OutlookSendMessagePayload,
+): Promise<void> {
+  await request<void>(connection, "/v1.0/me/sendMail", {
+    method: "POST",
+    body: JSON.stringify(message),
+  });
+}
+
+/** Reply to an existing message. */
+export async function replyToMessage(
+  connection: OAuthConnection,
+  messageId: string,
+  comment: string,
+): Promise<void> {
+  await request<void>(
+    connection,
+    `/v1.0/me/messages/${encodeURIComponent(messageId)}/reply`,
+    {
+      method: "POST",
+      body: JSON.stringify({ comment }),
+    },
+  );
+}
+
+/** List mail folders. */
+export async function listMailFolders(
+  connection: OAuthConnection,
+): Promise<OutlookMailFolder[]> {
+  const allFolders: OutlookMailFolder[] = [];
+  let nextQuery: Record<string, string> | undefined = { $top: "100" };
+
+  while (nextQuery) {
+    const resp = await request<OutlookMailFolderListResponse>(
+      connection,
+      "/v1.0/me/mailFolders",
+      undefined,
+      nextQuery,
+    );
+    if (resp.value) allFolders.push(...resp.value);
+    if (resp["@odata.nextLink"]) {
+      const nextUrl = new URL(resp["@odata.nextLink"]);
+      nextQuery = {};
+      nextUrl.searchParams.forEach((v, k) => {
+        nextQuery![k] = v;
+      });
+    } else {
+      nextQuery = undefined;
+    }
+  }
+
+  return allFolders;
+}
+
+/** Mark a message as read. */
+export async function markMessageRead(
+  connection: OAuthConnection,
+  messageId: string,
+): Promise<void> {
+  await request<void>(
+    connection,
+    `/v1.0/me/messages/${encodeURIComponent(messageId)}`,
+    {
+      method: "PATCH",
+      body: JSON.stringify({ isRead: true }),
+    },
+  );
+}
+
+/** Move a message to a different folder (e.g. for archiving). */
+export async function moveMessage(
+  connection: OAuthConnection,
+  messageId: string,
+  destinationFolderId: string,
+): Promise<OutlookMessage> {
+  return request<OutlookMessage>(
+    connection,
+    `/v1.0/me/messages/${encodeURIComponent(messageId)}/move`,
+    {
+      method: "POST",
+      body: JSON.stringify({ destinationId: destinationFolderId }),
+    },
+  );
+}
+
+/** Max concurrent individual getMessage requests for batch fetching. */
+const BATCH_CONCURRENCY = 5;
+
+/** Fetch multiple messages with concurrency limiting. */
+export async function batchGetMessages(
+  connection: OAuthConnection,
+  messageIds: string[],
+  select?: string,
+): Promise<OutlookMessage[]> {
+  if (messageIds.length === 0) return [];
+
+  if (messageIds.length === 1) {
+    return [await getMessage(connection, messageIds[0], select)];
+  }
+
+  const results: OutlookMessage[] = [];
+  for (let i = 0; i < messageIds.length; i += BATCH_CONCURRENCY) {
+    const wave = messageIds.slice(i, i + BATCH_CONCURRENCY);
+    const waveResults = await Promise.all(
+      wave.map((id) => getMessage(connection, id, select)),
+    );
+    results.push(...waveResults);
+  }
+  return results;
+}

package/src/messaging/providers/outlook/types.ts

@@ -0,0 +1,83 @@
+/** Minimal Outlook message reference from list endpoint */
+export interface OutlookMessageRef {
+  id: string;
+  conversationId: string;
+}
+
+/** Outlook message list/search response (paginated) */
+export interface OutlookMessageListResponse {
+  value?: OutlookMessage[];
+  "@odata.nextLink"?: string;
+  "@odata.count"?: number;
+}
+
+/** Email address in Microsoft Graph format */
+export interface OutlookEmailAddress {
+  name?: string;
+  address: string;
+}
+
+/** Recipient wrapper containing an email address */
+export interface OutlookRecipient {
+  emailAddress: OutlookEmailAddress;
+}
+
+/** Message body with content type */
+export interface OutlookItemBody {
+  contentType: "text" | "html";
+  content: string;
+}
+
+/** Full Outlook message from Microsoft Graph */
+export interface OutlookMessage {
+  id: string;
+  conversationId: string;
+  subject: string;
+  bodyPreview: string;
+  body: OutlookItemBody;
+  from?: OutlookRecipient;
+  toRecipients: OutlookRecipient[];
+  ccRecipients: OutlookRecipient[];
+  receivedDateTime: string; // ISO 8601
+  isRead: boolean;
+  hasAttachments: boolean;
+  parentFolderId: string;
+  categories: string[];
+  flag: {
+    flagStatus: "notFlagged" | "flagged" | "complete";
+  };
+}
+
+/** Outlook mail folder */
+export interface OutlookMailFolder {
+  id: string;
+  displayName: string;
+  totalItemCount?: number;
+  unreadItemCount?: number;
+  parentFolderId?: string;
+  childFolderCount?: number;
+}
+
+/** Outlook mail folder list response */
+export interface OutlookMailFolderListResponse {
+  value?: OutlookMailFolder[];
+  "@odata.nextLink"?: string;
+}
+
+/** Payload for sending a message via Microsoft Graph */
+export interface OutlookSendMessagePayload {
+  message: {
+    subject: string;
+    body: OutlookItemBody;
+    toRecipients: OutlookRecipient[];
+    ccRecipients?: OutlookRecipient[];
+  };
+  saveToSentItems?: boolean;
+}
+
+/** Microsoft Graph user profile */
+export interface OutlookUserProfile {
+  displayName: string;
+  mail: string;
+  userPrincipalName: string;
+}

package/src/notifications/adapters/slack.ts

@@ -153,7 +153,7 @@ export function buildAccessRequestBlocks(
       type: "section",
       text: {
         type: "mrkdwn",
-        text: `Reply *\`${code} approve\`* to grant access or *\`${code} reject\`* to deny.`,
+        text: `Reply *${code} approve* to grant access or *${code} reject* to deny.`,
       },
     });
   }

package/src/oauth/__tests__/identity-verifier.test.ts

@@ -38,7 +38,6 @@ function makeProviderRow(
     defaultScopes: "[]",
     scopePolicy: "{}",
     extraParams: null,
-    callbackTransport: null,
     pingUrl: null,
     pingMethod: null,
     pingHeaders: null,
@@ -60,6 +59,7 @@ function makeProviderRow(
     identityResponsePaths: null,
     identityFormat: null,
     identityOkField: null,
+    featureFlag: null,
     createdAt: now,
     updatedAt: now,
     ...rest,

package/src/oauth/connect-orchestrator.ts

@@ -68,6 +68,14 @@ export interface OAuthConnectOptions {
   /** Send a message to the client (e.g. open_url). */
   sendToClient?: (msg: { type: string; [key: string]: unknown }) => void;
 
+  /**
+   * Callback transport to use for the OAuth redirect.
+   * - `"loopback"` — start a local HTTP server (desktop clients).
+   * - `"gateway"` — use the public gateway ingress (web clients).
+   * Defaults to `"loopback"` when omitted.
+   */
+  callbackTransport?: "loopback" | "gateway";
+
   /**
    * Called when the deferred (non-interactive) flow completes — either
    * successfully after tokens are stored, or on failure. Lets callers
@@ -142,9 +150,8 @@ export async function orchestrateOAuthConnect(
   const tokenEndpointAuthMethod = providerRow.tokenEndpointAuthMethod as
     | TokenEndpointAuthMethod
     | undefined;
-  const callbackTransport =
-    (providerRow.callbackTransport as "loopback" | "gateway" | null) ??
-    "loopback";
+  const callbackTransport: "loopback" | "gateway" =
+    options.callbackTransport ?? "loopback";
   const loopbackPort = providerRow.loopbackPort ?? undefined;
 
   // Resolve scopes via the scope policy engine