@vellumai/assistant 0.3.0

package/src/messaging/provider-types.ts

@@ -0,0 +1,80 @@
+/** Platform-agnostic types for the messaging provider abstraction. */
+
+export interface Conversation {
+  id: string;
+  name: string;
+  type: 'channel' | 'dm' | 'group' | 'inbox' | 'thread';
+  platform: string;
+  unreadCount: number;
+  lastActivityAt: number;
+  memberCount?: number;
+  topic?: string;
+  isArchived?: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+export interface MessageSender {
+  id: string;
+  name: string;
+  email?: string;
+}
+
+export interface Message {
+  id: string;
+  conversationId: string;
+  sender: MessageSender;
+  text: string;
+  timestamp: number;
+  threadId?: string;
+  replyCount?: number;
+  platform: string;
+  reactions?: Array<{ name: string; count: number }>;
+  hasAttachments?: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+export interface SearchResult {
+  total: number;
+  messages: Message[];
+  hasMore: boolean;
+  nextCursor?: string;
+}
+
+export interface SendResult {
+  id: string;
+  timestamp: number;
+  conversationId: string;
+}
+
+export interface ConnectionInfo {
+  connected: boolean;
+  user: string;
+  platform: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ListOptions {
+  types?: Array<'channel' | 'dm' | 'group' | 'inbox'>;
+  excludeArchived?: boolean;
+  limit?: number;
+  cursor?: string;
+}
+
+export interface HistoryOptions {
+  limit?: number;
+  before?: string;
+  after?: string;
+}
+
+export interface SearchOptions {
+  count?: number;
+  cursor?: string;
+}
+
+export interface SendOptions {
+  threadId?: string;
+  /** For email: subject line */
+  subject?: string;
+  /** For email: in-reply-to message ID */
+  inReplyTo?: string;
+}

package/src/messaging/provider.ts

@@ -0,0 +1,52 @@
+/**
+ * MessagingProvider — the contract that all messaging platform adapters implement.
+ *
+ * Generic tools delegate to the provider, so adding a new platform is just
+ * implementing one adapter file + an OAuth setup skill.
+ */
+
+import type {
+  Conversation,
+  Message,
+  SearchResult,
+  SendResult,
+  ConnectionInfo,
+  ListOptions,
+  HistoryOptions,
+  SearchOptions,
+  SendOptions,
+} from './provider-types.js';
+
+export interface MessagingProvider {
+  /** Unique provider key (e.g. 'slack', 'gmail', 'discord'). */
+  id: string;
+  /** Human-readable name (e.g. 'Slack', 'Gmail'). */
+  displayName: string;
+  /** Credential service name for token-manager (e.g. 'integration:slack'). */
+  credentialService: string;
+
+  // ── Universal operations (every platform must implement) ──────────
+
+  testConnection(token: string): Promise<ConnectionInfo>;
+  listConversations(token: string, options?: ListOptions): Promise<Conversation[]>;
+  getHistory(token: string, conversationId: string, options?: HistoryOptions): Promise<Message[]>;
+  search(token: string, query: string, options?: SearchOptions): Promise<SearchResult>;
+  sendMessage(token: string, conversationId: string, text: string, options?: SendOptions): Promise<SendResult>;
+
+  // ── Optional operations (platforms implement what they support) ───
+
+  getThreadReplies?(token: string, conversationId: string, threadId: string, options?: HistoryOptions): Promise<Message[]>;
+  markRead?(token: string, conversationId: string, messageId?: string): Promise<void>;
+
+  /**
+   * Override the default credential check used by getConnectedProviders().
+   * When present, the registry calls this instead of looking for
+   * credential:${credentialService}:access_token. Useful for providers
+   * that don't use OAuth (e.g. Telegram bot tokens stored under a
+   * non-standard key).
+   */
+  isConnected?(): boolean;
+
+  /** Platform-specific capabilities for tool routing (e.g. 'reactions', 'threads', 'labels'). */
+  capabilities: Set<string>;
+}

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

@@ -0,0 +1,193 @@
+/**
+ * Gmail messaging provider adapter.
+ *
+ * Maps Gmail API responses to the platform-agnostic messaging types
+ * and implements the MessagingProvider interface.
+ */
+
+import type { MessagingProvider } from '../../provider.js';
+import type {
+  Conversation,
+  Message,
+  SearchResult,
+  SendResult,
+  ConnectionInfo,
+  ListOptions,
+  HistoryOptions,
+  SearchOptions,
+  SendOptions,
+} from '../../provider-types.js';
+import type { GmailMessage, GmailMessagePart } from './types.js';
+import * as gmail from './client.js';
+
+function extractHeader(msg: GmailMessage, name: string): string {
+  const lower = name.toLowerCase();
+  return msg.payload?.headers?.find(
+    (h) => h.name.toLowerCase() === lower,
+  )?.value ?? '';
+}
+
+function extractPlainTextBody(msg: GmailMessage): string {
+  if (!msg.payload) return '';
+
+  function walkParts(part: GmailMessagePart): string | null {
+    if (part.mimeType === 'text/plain' && part.body?.data) {
+      return Buffer.from(part.body.data, 'base64url').toString('utf-8');
+    }
+    if (part.parts) {
+      for (const child of part.parts) {
+        const result = walkParts(child);
+        if (result) return result;
+      }
+    }
+    return null;
+  }
+
+  return walkParts(msg.payload) ?? msg.snippet ?? '';
+}
+
+function mapGmailMessage(msg: GmailMessage): Message {
+  const from = extractHeader(msg, 'From');
+  const subject = extractHeader(msg, 'Subject');
+
+  // Parse sender name/email from "Name <email>" format
+  const emailMatch = from.match(/<([^>]+)>/);
+  const senderEmail = emailMatch?.[1] ?? from;
+  const senderName = emailMatch ? from.replace(/<[^>]+>/, '').trim() : from;
+
+  return {
+    id: msg.id,
+    conversationId: msg.threadId,
+    sender: { id: senderEmail, name: senderName || senderEmail, email: senderEmail },
+    text: extractPlainTextBody(msg),
+    timestamp: msg.internalDate ? parseInt(msg.internalDate, 10) : Date.now(),
+    threadId: msg.threadId,
+    platform: 'gmail',
+    hasAttachments: msg.payload?.parts?.some((p) => p.filename && p.filename.length > 0) ?? false,
+    metadata: {
+      subject,
+      labelIds: msg.labelIds,
+      snippet: msg.snippet,
+    },
+  };
+}
+
+export const gmailMessagingProvider: MessagingProvider = {
+  id: 'gmail',
+  displayName: 'Gmail',
+  credentialService: 'integration:gmail',
+  capabilities: new Set(['threads', 'labels', 'drafts_native', 'archive', 'unsubscribe']),
+
+  async testConnection(token: string): Promise<ConnectionInfo> {
+    const profile = await gmail.getProfile(token);
+    return {
+      connected: true,
+      user: profile.emailAddress,
+      platform: 'gmail',
+      metadata: {
+        messagesTotal: profile.messagesTotal,
+        threadsTotal: profile.threadsTotal,
+      },
+    };
+  },
+
+  async listConversations(token: string, _options?: ListOptions): Promise<Conversation[]> {
+    // Gmail "conversations" are modeled as labels with unread counts
+    const labels = await gmail.listLabels(token);
+    const conversations: Conversation[] = [];
+
+    for (const label of labels) {
+      // Only include meaningful labels
+      if (label.type === 'system' && !['INBOX', 'STARRED', 'IMPORTANT', 'SENT', 'DRAFT', 'SPAM', 'TRASH'].includes(label.id)) {
+        continue;
+      }
+
+      conversations.push({
+        id: label.id,
+        name: label.name,
+        type: 'inbox',
+        platform: 'gmail',
+        unreadCount: label.messagesUnread ?? 0,
+        lastActivityAt: Date.now(), // Gmail labels don't track last activity
+        metadata: {
+          messagesTotal: label.messagesTotal,
+          threadsTotal: label.threadsTotal,
+          labelType: label.type,
+        },
+      });
+    }
+
+    return conversations;
+  },
+
+  async getHistory(token: string, conversationId: string, options?: HistoryOptions): Promise<Message[]> {
+    // conversationId is a label ID — list messages in that label
+    const limit = options?.limit ?? 50;
+    const listResult = await gmail.listMessages(token, undefined, limit, undefined, [conversationId]);
+
+    if (!listResult.messages?.length) return [];
+
+    const messages = await gmail.batchGetMessages(
+      token,
+      listResult.messages.map((m) => m.id),
+      'full',
+    );
+
+    return messages.map(mapGmailMessage);
+  },
+
+  async search(token: string, query: string, options?: SearchOptions): Promise<SearchResult> {
+    const count = options?.count ?? 20;
+    const listResult = await gmail.listMessages(token, query, count);
+
+    if (!listResult.messages?.length) {
+      return { total: 0, messages: [], hasMore: false };
+    }
+
+    const messages = await gmail.batchGetMessages(
+      token,
+      listResult.messages.map((m) => m.id),
+      'full',
+    );
+
+    return {
+      total: listResult.resultSizeEstimate ?? messages.length,
+      messages: messages.map(mapGmailMessage),
+      hasMore: !!listResult.nextPageToken,
+      nextCursor: listResult.nextPageToken,
+    };
+  },
+
+  async sendMessage(token: string, conversationId: string, text: string, options?: SendOptions): Promise<SendResult> {
+    // conversationId is the recipient email for Gmail
+    const to = conversationId;
+    const subject = options?.subject ?? '';
+    const msg = await gmail.sendMessage(token, to, subject, text, options?.inReplyTo, options?.threadId);
+    return {
+      id: msg.id,
+      timestamp: msg.internalDate ? parseInt(msg.internalDate, 10) : Date.now(),
+      conversationId: msg.threadId,
+    };
+  },
+
+  async getThreadReplies(token: string, _conversationId: string, threadId: string, options?: HistoryOptions): Promise<Message[]> {
+    // Get all messages in a Gmail thread
+    const limit = options?.limit ?? 50;
+    const listResult = await gmail.listMessages(token, `thread:${threadId}`, limit);
+
+    if (!listResult.messages?.length) return [];
+
+    const messages = await gmail.batchGetMessages(
+      token,
+      listResult.messages.map((m) => m.id),
+      'full',
+    );
+
+    return messages.map(mapGmailMessage);
+  },
+
+  async markRead(token: string, _conversationId: string, messageId?: string): Promise<void> {
+    if (!messageId) return;
+    await gmail.modifyMessage(token, messageId, { removeLabelIds: ['UNREAD'] });
+  },
+};

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

@@ -0,0 +1,204 @@
+import type {
+  GmailMessage,
+  GmailMessageListResponse,
+  GmailLabel,
+  GmailLabelsListResponse,
+  GmailProfile,
+  GmailDraft,
+  GmailModifyRequest,
+  GmailMessageFormat,
+} from './types.js';
+
+const GMAIL_API_BASE = 'https://gmail.googleapis.com/gmail/v1/users/me';
+
+/** Max concurrent requests for batch operations */
+const BATCH_CONCURRENCY = 5;
+
+export class GmailApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly statusText: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'GmailApiError';
+  }
+}
+
+async function request<T>(token: string, path: string, options?: RequestInit): Promise<T> {
+  const url = `${GMAIL_API_BASE}${path}`;
+  const resp = await fetch(url, {
+    ...options,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+      ...options?.headers,
+    },
+  });
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => '');
+    throw new GmailApiError(resp.status, resp.statusText, `Gmail API ${resp.status}: ${body}`);
+  }
+  // Some endpoints (e.g. batchModify) return empty success responses
+  const contentLength = resp.headers.get('content-length');
+  if (resp.status === 204 || contentLength === '0') {
+    return undefined as T;
+  }
+  const text = await resp.text();
+  if (!text) return undefined as T;
+  return JSON.parse(text) as T;
+}
+
+/** List messages matching a query. */
+export async function listMessages(
+  token: string,
+  query?: string,
+  maxResults = 20,
+  pageToken?: string,
+  labelIds?: string[],
+): Promise<GmailMessageListResponse> {
+  const params = new URLSearchParams();
+  if (query) params.set('q', query);
+  params.set('maxResults', String(maxResults));
+  if (pageToken) params.set('pageToken', pageToken);
+  if (labelIds) {
+    for (const id of labelIds) params.append('labelIds', id);
+  }
+  return request<GmailMessageListResponse>(token, `/messages?${params}`);
+}
+
+/** Get a single message by ID. */
+export async function getMessage(
+  token: string,
+  messageId: string,
+  format: GmailMessageFormat = 'full',
+  metadataHeaders?: string[],
+): Promise<GmailMessage> {
+  const params = new URLSearchParams({ format });
+  if (format === 'metadata' && metadataHeaders) {
+    for (const h of metadataHeaders) params.append('metadataHeaders', h);
+  }
+  return request<GmailMessage>(token, `/messages/${messageId}?${params}`);
+}
+
+/** Get multiple messages in parallel with capped concurrency. */
+export async function batchGetMessages(
+  token: string,
+  messageIds: string[],
+  format: GmailMessageFormat = 'full',
+  metadataHeaders?: string[],
+): Promise<GmailMessage[]> {
+  const results: GmailMessage[] = [];
+  for (let i = 0; i < messageIds.length; i += BATCH_CONCURRENCY) {
+    const batch = messageIds.slice(i, i + BATCH_CONCURRENCY);
+    const batchResults = await Promise.all(
+      batch.map((id) => getMessage(token, id, format, metadataHeaders)),
+    );
+    results.push(...batchResults);
+  }
+  return results;
+}
+
+/** Modify labels on a single message. */
+export async function modifyMessage(
+  token: string,
+  messageId: string,
+  modifications: GmailModifyRequest,
+): Promise<GmailMessage> {
+  return request<GmailMessage>(token, `/messages/${messageId}/modify`, {
+    method: 'POST',
+    body: JSON.stringify(modifications),
+  });
+}
+
+/** Batch modify labels on multiple messages. */
+export async function batchModifyMessages(
+  token: string,
+  messageIds: string[],
+  modifications: GmailModifyRequest,
+): Promise<void> {
+  await request<void>(token, '/messages/batchModify', {
+    method: 'POST',
+    body: JSON.stringify({ ids: messageIds, ...modifications }),
+  });
+}
+
+/** Move a message to trash. */
+export async function trashMessage(
+  token: string,
+  messageId: string,
+): Promise<GmailMessage> {
+  return request<GmailMessage>(token, `/messages/${messageId}/trash`, {
+    method: 'POST',
+  });
+}
+
+/** List all labels. */
+export async function listLabels(token: string): Promise<GmailLabel[]> {
+  const resp = await request<GmailLabelsListResponse>(token, '/labels');
+  return resp.labels ?? [];
+}
+
+/** Create a draft. */
+export async function createDraft(
+  token: string,
+  to: string,
+  subject: string,
+  body: string,
+  inReplyTo?: string,
+): Promise<GmailDraft> {
+  const headers = [
+    `To: ${to}`,
+    `Subject: ${subject}`,
+    'Content-Type: text/plain; charset=utf-8',
+  ];
+  if (inReplyTo) {
+    headers.push(`In-Reply-To: ${inReplyTo}`);
+    headers.push(`References: ${inReplyTo}`);
+  }
+  const raw = Buffer.from(`${headers.join('\r\n')}\r\n\r\n${body}`, 'utf-8')
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+  return request<GmailDraft>(token, '/drafts', {
+    method: 'POST',
+    body: JSON.stringify({ message: { raw } }),
+  });
+}
+
+/** Send an email. */
+export async function sendMessage(
+  token: string,
+  to: string,
+  subject: string,
+  body: string,
+  inReplyTo?: string,
+  threadId?: string,
+): Promise<GmailMessage> {
+  const headers = [
+    `To: ${to}`,
+    `Subject: ${subject}`,
+    'Content-Type: text/plain; charset=utf-8',
+  ];
+  if (inReplyTo) {
+    headers.push(`In-Reply-To: ${inReplyTo}`);
+    headers.push(`References: ${inReplyTo}`);
+  }
+  const raw = Buffer.from(`${headers.join('\r\n')}\r\n\r\n${body}`, 'utf-8')
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+  const payload: Record<string, unknown> = { raw };
+  if (threadId) payload.threadId = threadId;
+  return request<GmailMessage>(token, '/messages/send', {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  });
+}
+
+/** Get the authenticated user's profile (email address). */
+export async function getProfile(token: string): Promise<GmailProfile> {
+  return request<GmailProfile>(token, '/profile');
+}

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

@@ -0,0 +1,90 @@
+/** Minimal Gmail message metadata from list endpoint */
+export interface GmailMessageRef {
+  id: string;
+  threadId: string;
+}
+
+/** Gmail message list response */
+export interface GmailMessageListResponse {
+  messages?: GmailMessageRef[];
+  nextPageToken?: string;
+  resultSizeEstimate?: number;
+}
+
+/** A single header key-value pair */
+export interface GmailHeader {
+  name: string;
+  value: string;
+}
+
+/** Message payload part (recursive for multipart) */
+export interface GmailMessagePart {
+  partId?: string;
+  mimeType?: string;
+  filename?: string;
+  headers?: GmailHeader[];
+  body?: {
+    attachmentId?: string;
+    size?: number;
+    data?: string; // base64url-encoded
+  };
+  parts?: GmailMessagePart[];
+}
+
+/** Full Gmail message */
+export interface GmailMessage {
+  id: string;
+  threadId: string;
+  labelIds?: string[];
+  snippet?: string;
+  historyId?: string;
+  internalDate?: string;
+  payload?: GmailMessagePart;
+  sizeEstimate?: number;
+  raw?: string;
+}
+
+/** Gmail label */
+export interface GmailLabel {
+  id: string;
+  name: string;
+  type?: 'system' | 'user';
+  messageListVisibility?: 'show' | 'hide';
+  labelListVisibility?: 'labelShow' | 'labelShowIfUnread' | 'labelHide';
+  messagesTotal?: number;
+  messagesUnread?: number;
+  threadsTotal?: number;
+  threadsUnread?: number;
+  color?: {
+    textColor?: string;
+    backgroundColor?: string;
+  };
+}
+
+/** Gmail labels list response */
+export interface GmailLabelsListResponse {
+  labels?: GmailLabel[];
+}
+
+/** Gmail profile response */
+export interface GmailProfile {
+  emailAddress: string;
+  messagesTotal?: number;
+  threadsTotal?: number;
+  historyId?: string;
+}
+
+/** Gmail draft response */
+export interface GmailDraft {
+  id: string;
+  message?: GmailMessage;
+}
+
+/** Modify request body */
+export interface GmailModifyRequest {
+  addLabelIds?: string[];
+  removeLabelIds?: string[];
+}
+
+/** Message format for GET requests */
+export type GmailMessageFormat = 'minimal' | 'full' | 'raw' | 'metadata';