@devosurf/tesser-connectors 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -2,7 +2,9 @@
 
 The Tesser connector library. **Apache-2.0** — connectors are permissive so the community and agents can contribute and embed them freely (ADR-0009). Never compile a connector into the AGPL server.
 
-> Status: **implemented.** P0 set: `github`, `slack`, `http`, `resend`, `gmail`, `google-calendar`. `pnpm codegen` assembles the registry (`index.ts`), the Catalog (`catalog/index.ts`) from provider declarations under `providers/`, and `manifest.json` — never hand-edit those three. Colocated `index.test.ts` runs against a fake fetch via `invokeAction`/`fakeFetch` from `@devosurf/tesser-testing`; `index.live.test.ts` suites hit real APIs (`pnpm test:live`, credentials from env, self-skipping).
+> Status: **implemented.** P0 set: `github`, `slack`, `http`, `resend`, `gmail`, `google-calendar`, plus the Microsoft Graph-backed `outlook-mail` mailbox connector. `pnpm codegen` assembles the registry (`index.ts`), the Catalog (`catalog/index.ts`) from provider declarations under `providers/`, and `manifest.json` — never hand-edit those three. Colocated `index.test.ts` runs against a fake fetch via `invokeAction`/`fakeFetch` from `@devosurf/tesser-testing`; `index.live.test.ts` suites hit real APIs (`pnpm test:live`, credentials from env, self-skipping).
+>
+> `outlook-mail` supports delegated Microsoft 365 user mailboxes by default and shared mailbox operations via the optional `mailbox` input, which targets Graph `/users/{userPrincipalName}` endpoints. It includes message list/get/send/reply/move/read-state/category helpers, draft create/reply/update/send, attachment get/list, mail folder list, master category list/create, and a delta-query `messageReceived` poll trigger. Graph webhook subscriptions remain future work because the runtime must own `validationToken` echoing and renewal.
 
 A connector is **our own** typed artifact — no Nango, no third-party OAuth code (ADR-0004). One connector per directory (`connectors/<name>/index.ts` + colocated tests + `sampleData`); a codegen step owns the registry, so you never hand-edit a global file. Auth is declared **once** and injected into every Action as a pre-authed `ctx.http` client — the author **never names a token** (`ctx.auth` is a masked escape hatch for odd placements). Actions are nested typed calls that return *our* stable shape, which `output` validates — never the raw provider response (ADR-0012):
 

package/catalog/index.ts

@@ -40,6 +40,19 @@ export const catalog: Record<string, ProviderFacts> = {
       }
     }
   },
+  "microsoft": {
+    "id": "microsoft",
+    "displayName": "Microsoft",
+    "baseUrl": "https://graph.microsoft.com/v1.0",
+    "docsUrl": "https://learn.microsoft.com/graph",
+    "oauth2": {
+      "authorizeUrl": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+      "tokenUrl": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+      "clientAuth": "body",
+      "scopeSeparator": " ",
+      "pkce": true
+    }
+  },
   "resend": {
     "id": "resend",
     "displayName": "Resend",

package/index.ts

@@ -10,6 +10,7 @@ export { default as googleDocs } from "./google-docs/index.js";
 export { default as googleDrive } from "./google-drive/index.js";
 export { default as googleSheets } from "./google-sheets/index.js";
 export { default as http } from "./http/index.js";
+export { default as outlookMail } from "./outlook-mail/index.js";
 export { default as pi } from "./pi/index.js";
 export { default as resend } from "./resend/index.js";
 export { default as slack } from "./slack/index.js";

package/manifest.json

@@ -599,6 +599,168 @@
       "triggers": [],
       "describe": "Plain HTTP requests to any endpoint"
     },
+    {
+      "id": "outlook-mail",
+      "auth": {
+        "default": {
+          "kind": "oauth2",
+          "scopes": [
+            "offline_access",
+            "Mail.Read",
+            "Mail.ReadWrite",
+            "Mail.Send",
+            "Mail.Read.Shared",
+            "Mail.ReadWrite.Shared",
+            "Mail.Send.Shared",
+            "MailboxSettings.Read",
+            "MailboxSettings.ReadWrite"
+          ],
+          "flow": "auth_code",
+          "provider": "microsoft"
+        }
+      },
+      "actions": [
+        {
+          "path": "messages.list",
+          "safety": "read",
+          "retrySafe": true,
+          "describe": "List messages in a folder using Microsoft Graph's stable mapped shape"
+        },
+        {
+          "path": "messages.listConversation",
+          "safety": "read",
+          "retrySafe": true,
+          "describe": "List messages in the same Outlook conversation"
+        },
+        {
+          "path": "messages.get",
+          "safety": "read",
+          "retrySafe": true,
+          "describe": "Fetch one message with body, recipients, categories, and thread ids"
+        },
+        {
+          "path": "messages.send",
+          "safety": "write",
+          "retrySafe": false,
+          "describe": "Send a new email using Outlook Mail (not idempotent; creates Sent Items mail)"
+        },
+        {
+          "path": "messages.reply",
+          "safety": "write",
+          "retrySafe": false,
+          "describe": "Send a reply to an existing message immediately (prefer drafts.createReply for human review)"
+        },
+        {
+          "path": "messages.markRead",
+          "safety": "write",
+          "retrySafe": true,
+          "describe": "Mark a message read (sets isRead=true)"
+        },
+        {
+          "path": "messages.setCategories",
+          "safety": "write",
+          "retrySafe": true,
+          "describe": "Replace a message's Outlook categories"
+        },
+        {
+          "path": "messages.addCategories",
+          "safety": "write",
+          "retrySafe": true,
+          "describe": "Add Outlook categories to a message without removing existing categories"
+        },
+        {
+          "path": "messages.removeCategories",
+          "safety": "write",
+          "retrySafe": true,
+          "describe": "Remove Outlook categories from a message"
+        },
+        {
+          "path": "messages.move",
+          "safety": "write",
+          "retrySafe": false,
+          "describe": "Move a message to another folder or well-known folder name (archive, deleteditems, junkemail, etc.)"
+        },
+        {
+          "path": "messages.attachments.list",
+          "safety": "read",
+          "retrySafe": true,
+          "describe": "List a message's attachments"
+        },
+        {
+          "path": "messages.attachments.get",
+          "safety": "read",
+          "retrySafe": true,
+          "describe": "Fetch one file attachment including base64 contentBytes when Graph returns them"
+        },
+        {
+          "path": "drafts.create",
+          "safety": "write",
+          "retrySafe": false,
+          "describe": "Create a new draft message for human review"
+        },
+        {
+          "path": "drafts.createReply",
+          "safety": "write",
+          "retrySafe": false,
+          "describe": "Create a reply draft for an existing message; send later with drafts.send"
+        },
+        {
+          "path": "drafts.update",
+          "safety": "write",
+          "retrySafe": true,
+          "describe": "Update a draft message's subject/body/recipients/categories"
+        },
+        {
+          "path": "drafts.send",
+          "safety": "write",
+          "retrySafe": false,
+          "describe": "Send an existing draft message (not idempotent)"
+        },
+        {
+          "path": "mailFolders.list",
+          "safety": "read",
+          "retrySafe": true,
+          "describe": "List root mail folders (well-known folders like inbox, archive, deleteditems can be used directly)"
+        },
+        {
+          "path": "categories.list",
+          "safety": "read",
+          "retrySafe": true,
+          "describe": "List the mailbox's Outlook master categories"
+        },
+        {
+          "path": "categories.create",
+          "safety": "write",
+          "retrySafe": false,
+          "describe": "Create an Outlook master category"
+        }
+      ],
+      "triggers": [
+        {
+          "id": "messageReceived",
+          "strategy": "poll",
+          "intervalDefault": "1m",
+          "intervalFloor": "30s",
+          "describe": "Fires for each new message created in an Outlook mail folder (delta-query poll)"
+        }
+      ],
+      "describe": "Outlook Mail via Microsoft Graph — read, draft, send, label, and organize mail as the connected account",
+      "provider": "microsoft",
+      "providerFacts": {
+        "id": "microsoft",
+        "displayName": "Microsoft",
+        "baseUrl": "https://graph.microsoft.com/v1.0",
+        "docsUrl": "https://learn.microsoft.com/graph",
+        "oauth2": {
+          "authorizeUrl": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+          "tokenUrl": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+          "clientAuth": "body",
+          "scopeSeparator": " ",
+          "pkce": true
+        }
+      },
+      "baseUrl": "https://graph.microsoft.com/v1.0"
+    },
     {
       "id": "pi",
       "auth": {

package/outlook-mail/index.ts

@@ -0,0 +1,901 @@
+// Outlook Mail connector — Microsoft Graph mail surface for support-agent style
+// inbox triage. Microsoft Graph sits behind the shared `microsoft` Provider so
+// Teams/Excel/OneDrive can reuse the same OAuth app and token family later.
+
+import { z } from "zod";
+import { RetryableError, TerminalError } from "@devosurf/tesser-sdk";
+import { action, defineConnector, oauth2, trigger, type ActionCtx } from "@devosurf/tesser-sdk/connector";
+import { microsoftProvider } from "../providers/microsoft.js";
+
+const SUMMARY_SELECT = [
+  "id",
+  "conversationId",
+  "subject",
+  "bodyPreview",
+  "receivedDateTime",
+  "webLink",
+  "isRead",
+  "hasAttachments",
+  "importance",
+  "categories",
+  "from",
+  "sender",
+  "parentFolderId",
+].join(",");
+
+const DETAIL_SELECT = [
+  SUMMARY_SELECT,
+  "body",
+  "toRecipients",
+  "ccRecipients",
+  "bccRecipients",
+  "replyTo",
+  "internetMessageId",
+  "isDraft",
+].join(",");
+
+const addressShape = z.object({ name: z.string(), address: z.string() });
+const messageSummaryShape = z.object({
+  id: z.string(),
+  conversationId: z.string(),
+  parentFolderId: z.string(),
+  from: z.string(),
+  fromName: z.string(),
+  subject: z.string(),
+  bodyPreview: z.string(),
+  receivedAt: z.string(),
+  webLink: z.string().optional(),
+  isRead: z.boolean(),
+  hasAttachments: z.boolean(),
+  categories: z.array(z.string()),
+  importance: z.string(),
+});
+const messageDetailShape = messageSummaryShape.extend({
+  body: z.string(),
+  bodyContentType: z.enum(["text", "html", "unknown"]),
+  to: z.array(addressShape),
+  cc: z.array(addressShape),
+  bcc: z.array(addressShape),
+  replyTo: z.array(addressShape),
+  internetMessageId: z.string().optional(),
+  isDraft: z.boolean(),
+});
+const folderShape = z.object({
+  id: z.string(),
+  displayName: z.string(),
+  parentFolderId: z.string(),
+  childFolderCount: z.number(),
+  unreadItemCount: z.number(),
+  totalItemCount: z.number(),
+  isHidden: z.boolean(),
+});
+const attachmentShape = z.object({
+  id: z.string(),
+  name: z.string(),
+  contentType: z.string(),
+  size: z.number(),
+  isInline: z.boolean(),
+});
+const attachmentDetailShape = attachmentShape.extend({ contentBytes: z.string() });
+const categoryShape = z.object({ id: z.string(), displayName: z.string(), color: z.string() });
+
+const mailboxInput = z.object({ mailbox: z.string().min(1).optional() });
+const recipientsInput = z.union([z.string().min(3), z.array(z.string().min(3)).min(1)]);
+const bodyContentTypeInput = z.enum(["text", "html"]).default("text");
+
+const composeInput = mailboxInput.extend({
+  to: recipientsInput,
+  subject: z.string(),
+  text: z.string(),
+  html: z.boolean().optional(),
+  cc: recipientsInput.optional(),
+  bcc: recipientsInput.optional(),
+  replyTo: recipientsInput.optional(),
+  from: z.string().min(3).optional(),
+  categories: z.array(z.string()).optional(),
+  importance: z.enum(["low", "normal", "high"]).optional(),
+});
+
+const sendInput = composeInput.extend({ saveToSentItems: z.boolean().optional() });
+
+const updateDraftInput = mailboxInput.extend({
+  id: z.string().min(1),
+  to: recipientsInput.optional(),
+  subject: z.string().optional(),
+  text: z.string().optional(),
+  html: z.boolean().optional(),
+  cc: recipientsInput.optional(),
+  bcc: recipientsInput.optional(),
+  replyTo: recipientsInput.optional(),
+  from: z.string().min(3).optional(),
+  categories: z.array(z.string()).optional(),
+  importance: z.enum(["low", "normal", "high"]).optional(),
+});
+
+type RawEmailAddress = { name?: string; address?: string };
+type RawRecipient = { emailAddress?: RawEmailAddress };
+type RawMessage = {
+  id: string;
+  conversationId?: string;
+  parentFolderId?: string;
+  from?: RawRecipient;
+  sender?: RawRecipient;
+  subject?: string;
+  bodyPreview?: string;
+  receivedDateTime?: string;
+  webLink?: string;
+  isRead?: boolean;
+  hasAttachments?: boolean;
+  categories?: string[];
+  importance?: string;
+  body?: { contentType?: string; content?: string };
+  toRecipients?: RawRecipient[];
+  ccRecipients?: RawRecipient[];
+  bccRecipients?: RawRecipient[];
+  replyTo?: RawRecipient[];
+  internetMessageId?: string;
+  isDraft?: boolean;
+  "@removed"?: { reason?: string };
+};
+type RawFolder = {
+  id: string;
+  displayName?: string;
+  parentFolderId?: string;
+  childFolderCount?: number;
+  unreadItemCount?: number;
+  totalItemCount?: number;
+  isHidden?: boolean;
+};
+type RawAttachment = {
+  id: string;
+  name?: string;
+  contentType?: string;
+  size?: number;
+  isInline?: boolean;
+  contentBytes?: string;
+};
+type RawCategory = { id: string; displayName?: string; color?: string };
+type DeltaCursor = { mailbox?: string; folderId: string; link: string; seeded: boolean };
+type GraphCollection<T> = {
+  value?: T[];
+  "@odata.nextLink"?: string;
+  "@odata.deltaLink"?: string;
+};
+
+function address(raw: RawRecipient | undefined): z.infer<typeof addressShape> {
+  return {
+    name: raw?.emailAddress?.name ?? "",
+    address: raw?.emailAddress?.address ?? "",
+  };
+}
+
+function addresses(raw: RawRecipient[] | undefined): Array<z.infer<typeof addressShape>> {
+  return (raw ?? []).map(address);
+}
+
+function mapSummary(raw: RawMessage): z.infer<typeof messageSummaryShape> {
+  const from = address(raw.from ?? raw.sender);
+  return {
+    id: raw.id,
+    conversationId: raw.conversationId ?? "",
+    parentFolderId: raw.parentFolderId ?? "",
+    from: from.address,
+    fromName: from.name,
+    subject: raw.subject ?? "",
+    bodyPreview: raw.bodyPreview ?? "",
+    receivedAt: raw.receivedDateTime ?? "",
+    ...(raw.webLink !== undefined ? { webLink: raw.webLink } : {}),
+    isRead: raw.isRead ?? false,
+    hasAttachments: raw.hasAttachments ?? false,
+    categories: raw.categories ?? [],
+    importance: raw.importance ?? "normal",
+  };
+}
+
+function mapDetail(raw: RawMessage): z.infer<typeof messageDetailShape> {
+  const contentType = (raw.body?.contentType ?? "unknown").toLowerCase();
+  return {
+    ...mapSummary(raw),
+    body: raw.body?.content ?? "",
+    bodyContentType: contentType === "text" || contentType === "html" ? contentType : "unknown",
+    to: addresses(raw.toRecipients),
+    cc: addresses(raw.ccRecipients),
+    bcc: addresses(raw.bccRecipients),
+    replyTo: addresses(raw.replyTo),
+    ...(raw.internetMessageId !== undefined ? { internetMessageId: raw.internetMessageId } : {}),
+    isDraft: raw.isDraft ?? false,
+  };
+}
+
+function mapFolder(raw: RawFolder): z.infer<typeof folderShape> {
+  return {
+    id: raw.id,
+    displayName: raw.displayName ?? "",
+    parentFolderId: raw.parentFolderId ?? "",
+    childFolderCount: raw.childFolderCount ?? 0,
+    unreadItemCount: raw.unreadItemCount ?? 0,
+    totalItemCount: raw.totalItemCount ?? 0,
+    isHidden: raw.isHidden ?? false,
+  };
+}
+
+function mapAttachment(raw: RawAttachment): z.infer<typeof attachmentShape> {
+  return {
+    id: raw.id,
+    name: raw.name ?? "",
+    contentType: raw.contentType ?? "",
+    size: raw.size ?? 0,
+    isInline: raw.isInline ?? false,
+  };
+}
+
+function mapAttachmentDetail(raw: RawAttachment): z.infer<typeof attachmentDetailShape> {
+  return { ...mapAttachment(raw), contentBytes: raw.contentBytes ?? "" };
+}
+
+function mapCategory(raw: RawCategory): z.infer<typeof categoryShape> {
+  return { id: raw.id, displayName: raw.displayName ?? "", color: raw.color ?? "" };
+}
+
+function recipientObjects(input: z.infer<typeof recipientsInput> | undefined): RawRecipient[] | undefined {
+  if (input === undefined) return undefined;
+  const values = Array.isArray(input) ? input : [input];
+  return values.map((address) => ({ emailAddress: { address } }));
+}
+
+function messagePayload(input: z.infer<typeof composeInput>): Record<string, unknown> {
+  return {
+    subject: input.subject,
+    body: { contentType: input.html === true ? "HTML" : "Text", content: input.text },
+    toRecipients: recipientObjects(input.to),
+    ...(input.cc !== undefined ? { ccRecipients: recipientObjects(input.cc) } : {}),
+    ...(input.bcc !== undefined ? { bccRecipients: recipientObjects(input.bcc) } : {}),
+    ...(input.replyTo !== undefined ? { replyTo: recipientObjects(input.replyTo) } : {}),
+    ...(input.from !== undefined ? { from: { emailAddress: { address: input.from } } } : {}),
+    ...(input.categories !== undefined ? { categories: input.categories } : {}),
+    ...(input.importance !== undefined ? { importance: input.importance } : {}),
+  };
+}
+
+function draftPatch(input: z.infer<typeof updateDraftInput>): Record<string, unknown> {
+  return {
+    ...(input.subject !== undefined ? { subject: input.subject } : {}),
+    ...(input.text !== undefined ? { body: { contentType: input.html === true ? "HTML" : "Text", content: input.text } } : {}),
+    ...(input.to !== undefined ? { toRecipients: recipientObjects(input.to) } : {}),
+    ...(input.cc !== undefined ? { ccRecipients: recipientObjects(input.cc) } : {}),
+    ...(input.bcc !== undefined ? { bccRecipients: recipientObjects(input.bcc) } : {}),
+    ...(input.replyTo !== undefined ? { replyTo: recipientObjects(input.replyTo) } : {}),
+    ...(input.from !== undefined ? { from: { emailAddress: { address: input.from } } } : {}),
+    ...(input.categories !== undefined ? { categories: input.categories } : {}),
+    ...(input.importance !== undefined ? { importance: input.importance } : {}),
+  };
+}
+
+function mailboxRoot(mailbox?: string): string {
+  return mailbox !== undefined ? `/users/${encodeURIComponent(mailbox)}` : "/me";
+}
+
+function messagePath(id: string, mailbox?: string): string {
+  return `${mailboxRoot(mailbox)}/messages/${encodeURIComponent(id)}`;
+}
+
+function folderMessagesPath(folderId: string, mailbox?: string): string {
+  return `${mailboxRoot(mailbox)}/mailFolders/${encodeURIComponent(folderId)}/messages`;
+}
+
+function masterCategoriesPath(mailbox?: string): string {
+  return `${mailboxRoot(mailbox)}/outlook/masterCategories`;
+}
+
+async function listCollection<T>(
+  ctx: ActionCtx,
+  firstPath: string,
+  query: Record<string, string | number | boolean | undefined>,
+  limit: number,
+): Promise<T[]> {
+  const out: T[] = [];
+  let path = firstPath;
+  for (let page = 0; page < 50 && out.length < limit; page++) {
+    const res = (await ctx.http.get(path, page === 0 ? { query } : undefined)) as GraphCollection<T>;
+    out.push(...(res.value ?? []));
+    if (!res["@odata.nextLink"]) return out.slice(0, limit);
+    path = res["@odata.nextLink"];
+  }
+  if (out.length >= limit) return out.slice(0, limit);
+  throw new RetryableError(`microsoft graph pagination exceeded safety cap for ${firstPath}`);
+}
+
+function escapeODataString(value: string): string {
+  return value.replace(/'/g, "''");
+}
+
+function cursorMatches(cursor: DeltaCursor, mailbox: string | undefined, folderId: string): boolean {
+  return (cursor.mailbox ?? undefined) === mailbox && cursor.folderId === folderId;
+}
+
+function cursorFromString(cursor: string, mailbox: string | undefined, folderId: string): DeltaCursor | undefined {
+  if (mailbox !== undefined) return undefined; // legacy alpha.2 cursors only targeted /me.
+  try {
+    const path = new URL(cursor).pathname;
+    if (!path.includes(`/mailFolders/${encodeURIComponent(folderId)}/messages/delta`)) return undefined;
+  } catch {
+    return undefined;
+  }
+  return { folderId, link: cursor, seeded: true };
+}
+
+function normalizeCursor(cursor: unknown, mailbox: string | undefined, folderId: string): DeltaCursor | undefined {
+  if (typeof cursor === "string" && cursor.length > 0) return cursorFromString(cursor, mailbox, folderId);
+  if (cursor && typeof cursor === "object") {
+    const c = cursor as Partial<DeltaCursor>;
+    if (typeof c.folderId === "string" && typeof c.link === "string" && typeof c.seeded === "boolean") {
+      const normalized: DeltaCursor = {
+        ...(typeof c.mailbox === "string" ? { mailbox: c.mailbox } : {}),
+        folderId: c.folderId,
+        link: c.link,
+        seeded: c.seeded,
+      };
+      return cursorMatches(normalized, mailbox, folderId) ? normalized : undefined;
+    }
+  }
+  return undefined;
+}
+
+async function pollCreatedMessages(
+  ctx: ActionCtx,
+  mailbox: string | undefined,
+  folderId: string,
+  maxPageSize: number,
+  cursor: unknown,
+): Promise<{ items: RawMessage[]; nextCursor?: DeltaCursor }> {
+  const current = normalizeCursor(cursor, mailbox, folderId);
+  const first = current === undefined;
+  const res = (await ctx.http.get(current?.link ?? `${folderMessagesPath(folderId, mailbox)}/delta`, {
+    ...(first
+      ? {
+          query: {
+            changeType: "created",
+            $select: SUMMARY_SELECT,
+            $orderby: "receivedDateTime desc",
+            $top: maxPageSize,
+          },
+        }
+      : {}),
+    headers: { Prefer: `odata.maxpagesize=${maxPageSize}` },
+  })) as GraphCollection<RawMessage>;
+  const seeded = current?.seeded ?? false;
+  const rawItems = (res.value ?? []).filter((m) => m["@removed"] === undefined);
+  const cursorTarget = { ...(mailbox !== undefined ? { mailbox } : {}), folderId };
+  if (res["@odata.deltaLink"] !== undefined) {
+    return {
+      items: seeded ? rawItems : [],
+      nextCursor: { ...cursorTarget, link: res["@odata.deltaLink"], seeded: true },
+    };
+  }
+  if (res["@odata.nextLink"] !== undefined) {
+    return {
+      items: seeded ? rawItems : [],
+      nextCursor: { ...cursorTarget, link: res["@odata.nextLink"], seeded },
+    };
+  }
+  return { items: seeded ? rawItems : [] };
+}
+
+function preferBody(contentType: "text" | "html", allowUnsafeHtml?: boolean): string {
+  const parts = [`outlook.body-content-type=\"${contentType}\"`];
+  if (allowUnsafeHtml === true) parts.push("outlook.allow-unsafe-html");
+  return parts.join(", ");
+}
+
+export default defineConnector({
+  id: "outlook-mail",
+  describe: "Outlook Mail via Microsoft Graph — read, draft, send, label, and organize mail as the connected account",
+  provider: microsoftProvider,
+  baseUrl: "https://graph.microsoft.com/v1.0",
+  auth: oauth2({
+    provider: "microsoft",
+    scopes: [
+      "offline_access",
+      "Mail.Read",
+      "Mail.ReadWrite",
+      "Mail.Send",
+      "Mail.Read.Shared",
+      "Mail.ReadWrite.Shared",
+      "Mail.Send.Shared",
+      "MailboxSettings.Read",
+      "MailboxSettings.ReadWrite",
+    ],
+  }),
+  defaultHeaders: {
+    accept: "application/json",
+  },
+  samples: {
+    "messages.list": [
+      {
+        id: "AAMkAD1",
+        conversationId: "AAQkAD1",
+        parentFolderId: "inbox",
+        from: "ada@example.com",
+        fromName: "Ada",
+        subject: "sample subject",
+        bodyPreview: "hello",
+        receivedAt: "2026-01-01T00:00:00Z",
+        webLink: "https://outlook.office.com/mail/inbox/id/AAMkAD1",
+        isRead: false,
+        hasAttachments: false,
+        categories: [],
+        importance: "normal",
+      },
+    ],
+    "messages.listConversation": [
+      {
+        id: "AAMkAD1",
+        conversationId: "AAQkAD1",
+        parentFolderId: "inbox",
+        from: "ada@example.com",
+        fromName: "Ada",
+        subject: "sample subject",
+        bodyPreview: "hello",
+        receivedAt: "2026-01-01T00:00:00Z",
+        isRead: false,
+        hasAttachments: false,
+        categories: [],
+        importance: "normal",
+      },
+    ],
+    "messages.get": {
+      id: "AAMkAD1",
+      conversationId: "AAQkAD1",
+      parentFolderId: "inbox",
+      from: "ada@example.com",
+      fromName: "Ada",
+      subject: "sample subject",
+      bodyPreview: "hello",
+      receivedAt: "2026-01-01T00:00:00Z",
+      isRead: false,
+      hasAttachments: false,
+      categories: [],
+      importance: "normal",
+      body: "hello there",
+      bodyContentType: "text",
+      to: [{ name: "Support", address: "support@example.com" }],
+      cc: [],
+      bcc: [],
+      replyTo: [],
+      internetMessageId: "<m1@example.com>",
+      isDraft: false,
+    },
+    "messages.send": { accepted: true },
+    "messages.reply": { accepted: true },
+    "messages.markRead": {
+      id: "AAMkAD1",
+      conversationId: "AAQkAD1",
+      parentFolderId: "inbox",
+      from: "ada@example.com",
+      fromName: "Ada",
+      subject: "sample subject",
+      bodyPreview: "hello",
+      receivedAt: "2026-01-01T00:00:00Z",
+      isRead: true,
+      hasAttachments: false,
+      categories: [],
+      importance: "normal",
+    },
+    "messages.setCategories": {
+      id: "AAMkAD1",
+      conversationId: "AAQkAD1",
+      parentFolderId: "inbox",
+      from: "ada@example.com",
+      fromName: "Ada",
+      subject: "sample subject",
+      bodyPreview: "hello",
+      receivedAt: "2026-01-01T00:00:00Z",
+      isRead: true,
+      hasAttachments: false,
+      categories: ["Support"],
+      importance: "normal",
+    },
+    "messages.addCategories": {
+      id: "AAMkAD1",
+      conversationId: "AAQkAD1",
+      parentFolderId: "inbox",
+      from: "ada@example.com",
+      fromName: "Ada",
+      subject: "sample subject",
+      bodyPreview: "hello",
+      receivedAt: "2026-01-01T00:00:00Z",
+      isRead: true,
+      hasAttachments: false,
+      categories: ["Support", "Escalated"],
+      importance: "normal",
+    },
+    "messages.removeCategories": {
+      id: "AAMkAD1",
+      conversationId: "AAQkAD1",
+      parentFolderId: "inbox",
+      from: "ada@example.com",
+      fromName: "Ada",
+      subject: "sample subject",
+      bodyPreview: "hello",
+      receivedAt: "2026-01-01T00:00:00Z",
+      isRead: true,
+      hasAttachments: false,
+      categories: ["Support"],
+      importance: "normal",
+    },
+    "messages.move": {
+      id: "AAMkAD2",
+      conversationId: "AAQkAD1",
+      parentFolderId: "archive",
+      from: "ada@example.com",
+      fromName: "Ada",
+      subject: "sample subject",
+      bodyPreview: "hello",
+      receivedAt: "2026-01-01T00:00:00Z",
+      isRead: true,
+      hasAttachments: false,
+      categories: [],
+      importance: "normal",
+    },
+    "messages.attachments.list": [
+      { id: "att1", name: "invoice.pdf", contentType: "application/pdf", size: 1234, isInline: false },
+    ],
+    "messages.attachments.get": {
+      id: "att1",
+      name: "invoice.pdf",
+      contentType: "application/pdf",
+      size: 1234,
+      isInline: false,
+      contentBytes: "JVBERi0=",
+    },
+    "drafts.create": {
+      id: "draft1",
+      conversationId: "conv1",
+      parentFolderId: "drafts",
+      from: "support@example.com",
+      fromName: "Support",
+      subject: "Re: hello",
+      bodyPreview: "reply",
+      receivedAt: "2026-01-01T00:00:00Z",
+      isRead: true,
+      hasAttachments: false,
+      categories: [],
+      importance: "normal",
+      body: "reply",
+      bodyContentType: "text",
+      to: [{ name: "Ada", address: "ada@example.com" }],
+      cc: [],
+      bcc: [],
+      replyTo: [],
+      isDraft: true,
+    },
+    "drafts.createReply": {
+      id: "replyDraft1",
+      conversationId: "conv1",
+      parentFolderId: "drafts",
+      from: "support@example.com",
+      fromName: "Support",
+      subject: "Re: hello",
+      bodyPreview: "reply",
+      receivedAt: "2026-01-01T00:00:00Z",
+      isRead: true,
+      hasAttachments: false,
+      categories: [],
+      importance: "normal",
+      body: "reply",
+      bodyContentType: "text",
+      to: [{ name: "Ada", address: "ada@example.com" }],
+      cc: [],
+      bcc: [],
+      replyTo: [],
+      isDraft: true,
+    },
+    "drafts.update": {
+      id: "draft1",
+      conversationId: "conv1",
+      parentFolderId: "drafts",
+      from: "support@example.com",
+      fromName: "Support",
+      subject: "Re: hello",
+      bodyPreview: "updated",
+      receivedAt: "2026-01-01T00:00:00Z",
+      isRead: true,
+      hasAttachments: false,
+      categories: [],
+      importance: "normal",
+      body: "updated",
+      bodyContentType: "text",
+      to: [{ name: "Ada", address: "ada@example.com" }],
+      cc: [],
+      bcc: [],
+      replyTo: [],
+      isDraft: true,
+    },
+    "drafts.send": { accepted: true },
+    "mailFolders.list": [
+      {
+        id: "inbox",
+        displayName: "Inbox",
+        parentFolderId: "root",
+        childFolderCount: 0,
+        unreadItemCount: 3,
+        totalItemCount: 10,
+        isHidden: false,
+      },
+    ],
+    "categories.list": [{ id: "cat1", displayName: "Support", color: "preset0" }],
+    "categories.create": { id: "cat2", displayName: "Escalated", color: "preset1" },
+    "trigger:messageReceived": {
+      id: "AAMkAD3",
+      conversationId: "AAQkAD3",
+      parentFolderId: "inbox",
+      from: "ada@example.com",
+      fromName: "Ada",
+      subject: "new mail",
+      bodyPreview: "hello",
+      receivedAt: "2026-01-01T00:00:00Z",
+      isRead: false,
+      hasAttachments: false,
+      categories: [],
+      importance: "normal",
+    },
+  },
+  actions: {
+    messages: {
+      list: action({
+        describe: "List messages in a folder using Microsoft Graph's stable mapped shape",
+        input: mailboxInput.extend({
+          folderId: z.string().default("inbox"),
+          filter: z.string().optional(),
+          maxResults: z.number().int().min(1).max(250).default(25),
+        }),
+        output: z.array(messageSummaryShape),
+        safety: "read",
+        run: async (ctx, i) => {
+          const raw = await listCollection<RawMessage>(
+            ctx,
+            folderMessagesPath(i.folderId, i.mailbox),
+            {
+              $select: SUMMARY_SELECT,
+              $orderby: "receivedDateTime desc",
+              $top: Math.min(i.maxResults, 100),
+              ...(i.filter !== undefined ? { $filter: i.filter } : {}),
+            },
+            i.maxResults,
+          );
+          return raw.map(mapSummary);
+        },
+      }),
+      listConversation: action({
+        describe: "List messages in the same Outlook conversation",
+        input: mailboxInput.extend({
+          conversationId: z.string().min(1),
+          folderId: z.string().optional(),
+          maxResults: z.number().int().min(1).max(250).default(50),
+        }),
+        output: z.array(messageSummaryShape),
+        safety: "read",
+        run: async (ctx, i) => {
+          const raw = await listCollection<RawMessage>(
+            ctx,
+            i.folderId !== undefined ? folderMessagesPath(i.folderId, i.mailbox) : `${mailboxRoot(i.mailbox)}/messages`,
+            {
+              $select: SUMMARY_SELECT,
+              $filter: `conversationId eq '${escapeODataString(i.conversationId)}'`,
+              $orderby: "receivedDateTime desc",
+              $top: Math.min(i.maxResults, 100),
+            },
+            i.maxResults,
+          );
+          return raw.map(mapSummary);
+        },
+      }),
+      get: action({
+        describe: "Fetch one message with body, recipients, categories, and thread ids",
+        input: mailboxInput.extend({
+          id: z.string().min(1),
+          bodyContentType: bodyContentTypeInput,
+          allowUnsafeHtml: z.boolean().optional(),
+        }),
+        output: messageDetailShape,
+        safety: "read",
+        run: async (ctx, i) => {
+          const raw = (await ctx.http.get(messagePath(i.id, i.mailbox), {
+            query: { $select: DETAIL_SELECT },
+            headers: { Prefer: preferBody(i.bodyContentType, i.allowUnsafeHtml) },
+          })) as RawMessage;
+          return mapDetail(raw);
+        },
+      }),
+      send: action({
+        describe: "Send a new email using Outlook Mail (not idempotent; creates Sent Items mail)",
+        input: sendInput,
+        output: z.object({ accepted: z.boolean() }),
+        run: async (ctx, i) => {
+          await ctx.http.post(`${mailboxRoot(i.mailbox)}/sendMail`, {
+            message: messagePayload(i),
+            ...(i.saveToSentItems !== undefined ? { saveToSentItems: i.saveToSentItems } : {}),
+          });
+          return { accepted: true };
+        },
+      }),
+      reply: action({
+        describe: "Send a reply to an existing message immediately (prefer drafts.createReply for human review)",
+        input: mailboxInput.extend({
+          id: z.string().min(1),
+          comment: z.string().optional(),
+          to: recipientsInput.optional(),
+        }),
+        output: z.object({ accepted: z.boolean() }),
+        run: async (ctx, i) => {
+          await ctx.http.post(`${messagePath(i.id, i.mailbox)}/reply`, {
+            ...(i.comment !== undefined ? { comment: i.comment } : {}),
+            ...(i.to !== undefined ? { message: { toRecipients: recipientObjects(i.to) } } : {}),
+          });
+          return { accepted: true };
+        },
+      }),
+      markRead: action({
+        describe: "Mark a message read (sets isRead=true)",
+        input: mailboxInput.extend({ id: z.string().min(1) }),
+        output: messageSummaryShape,
+        retrySafe: true,
+        run: async (ctx, i) => mapSummary((await ctx.http.patch(messagePath(i.id, i.mailbox), { isRead: true })) as RawMessage),
+      }),
+      setCategories: action({
+        describe: "Replace a message's Outlook categories",
+        input: mailboxInput.extend({ id: z.string().min(1), categories: z.array(z.string()) }),
+        output: messageSummaryShape,
+        retrySafe: true,
+        run: async (ctx, i) =>
+          mapSummary((await ctx.http.patch(messagePath(i.id, i.mailbox), { categories: i.categories })) as RawMessage),
+      }),
+      addCategories: action({
+        describe: "Add Outlook categories to a message without removing existing categories",
+        input: mailboxInput.extend({ id: z.string().min(1), categories: z.array(z.string()).min(1) }),
+        output: messageSummaryShape,
+        retrySafe: true,
+        run: async (ctx, i) => {
+          const current = (await ctx.http.get(messagePath(i.id, i.mailbox), { query: { $select: "id,categories" } })) as RawMessage;
+          const next = [...new Set([...(current.categories ?? []), ...i.categories])];
+          return mapSummary((await ctx.http.patch(messagePath(i.id, i.mailbox), { categories: next })) as RawMessage);
+        },
+      }),
+      removeCategories: action({
+        describe: "Remove Outlook categories from a message",
+        input: mailboxInput.extend({ id: z.string().min(1), categories: z.array(z.string()).min(1) }),
+        output: messageSummaryShape,
+        retrySafe: true,
+        run: async (ctx, i) => {
+          const remove = new Set(i.categories);
+          const current = (await ctx.http.get(messagePath(i.id, i.mailbox), { query: { $select: "id,categories" } })) as RawMessage;
+          const next = (current.categories ?? []).filter((category) => !remove.has(category));
+          return mapSummary((await ctx.http.patch(messagePath(i.id, i.mailbox), { categories: next })) as RawMessage);
+        },
+      }),
+      move: action({
+        describe: "Move a message to another folder or well-known folder name (archive, deleteditems, junkemail, etc.)",
+        input: mailboxInput.extend({ id: z.string().min(1), destinationId: z.string().min(1) }),
+        output: messageSummaryShape,
+        run: async (ctx, i) =>
+          mapSummary((await ctx.http.post(`${messagePath(i.id, i.mailbox)}/move`, { destinationId: i.destinationId })) as RawMessage),
+      }),
+      attachments: {
+        list: action({
+          describe: "List a message's attachments",
+          input: mailboxInput.extend({ messageId: z.string().min(1) }),
+          output: z.array(attachmentShape),
+          safety: "read",
+          run: async (ctx, i) => {
+            const raw = (await ctx.http.get(`${messagePath(i.messageId, i.mailbox)}/attachments`)) as GraphCollection<RawAttachment>;
+            return (raw.value ?? []).map(mapAttachment);
+          },
+        }),
+        get: action({
+          describe: "Fetch one file attachment including base64 contentBytes when Graph returns them",
+          input: mailboxInput.extend({ messageId: z.string().min(1), id: z.string().min(1) }),
+          output: attachmentDetailShape,
+          safety: "read",
+          run: async (ctx, i) =>
+            mapAttachmentDetail(
+              (await ctx.http.get(`${messagePath(i.messageId, i.mailbox)}/attachments/${encodeURIComponent(i.id)}`)) as RawAttachment,
+            ),
+        }),
+      },
+    },
+    drafts: {
+      create: action({
+        describe: "Create a new draft message for human review",
+        input: composeInput,
+        output: messageDetailShape,
+        run: async (ctx, i) => mapDetail((await ctx.http.post(`${mailboxRoot(i.mailbox)}/messages`, messagePayload(i))) as RawMessage),
+      }),
+      createReply: action({
+        describe: "Create a reply draft for an existing message; send later with drafts.send",
+        input: mailboxInput.extend({
+          messageId: z.string().min(1),
+          comment: z.string().optional(),
+          text: z.string().optional(),
+          html: z.boolean().optional(),
+        }),
+        output: messageDetailShape,
+        run: async (ctx, i) => {
+          if (i.comment !== undefined && i.text !== undefined) {
+            throw new TerminalError("outlook-mail.drafts.createReply: pass either comment or text, not both");
+          }
+          const body =
+            i.text !== undefined
+              ? { message: { body: { contentType: i.html === true ? "HTML" : "Text", content: i.text } } }
+              : i.comment !== undefined
+                ? { comment: i.comment }
+                : undefined;
+          return mapDetail((await ctx.http.post(`${messagePath(i.messageId, i.mailbox)}/createReply`, body)) as RawMessage);
+        },
+      }),
+      update: action({
+        describe: "Update a draft message's subject/body/recipients/categories",
+        input: updateDraftInput,
+        output: messageDetailShape,
+        retrySafe: true,
+        run: async (ctx, i) => mapDetail((await ctx.http.patch(messagePath(i.id, i.mailbox), draftPatch(i))) as RawMessage),
+      }),
+      send: action({
+        describe: "Send an existing draft message (not idempotent)",
+        input: mailboxInput.extend({ id: z.string().min(1) }),
+        output: z.object({ accepted: z.boolean() }),
+        run: async (ctx, i) => {
+          await ctx.http.post(`${messagePath(i.id, i.mailbox)}/send`);
+          return { accepted: true };
+        },
+      }),
+    },
+    mailFolders: {
+      list: action({
+        describe: "List root mail folders (well-known folders like inbox, archive, deleteditems can be used directly)",
+        input: mailboxInput.extend({ includeHiddenFolders: z.boolean().default(false), maxResults: z.number().int().min(1).max(250).default(100) }),
+        output: z.array(folderShape),
+        safety: "read",
+        run: async (ctx, i) => {
+          const raw = await listCollection<RawFolder>(
+            ctx,
+            `${mailboxRoot(i.mailbox)}/mailFolders`,
+            { includeHiddenFolders: i.includeHiddenFolders, $top: Math.min(i.maxResults, 100) },
+            i.maxResults,
+          );
+          return raw.map(mapFolder);
+        },
+      }),
+    },
+    categories: {
+      list: action({
+        describe: "List the mailbox's Outlook master categories",
+        input: mailboxInput.extend({}),
+        output: z.array(categoryShape),
+        safety: "read",
+        run: async (ctx, i) => {
+          const raw = (await ctx.http.get(masterCategoriesPath(i.mailbox))) as GraphCollection<RawCategory>;
+          return (raw.value ?? []).map(mapCategory);
+        },
+      }),
+      create: action({
+        describe: "Create an Outlook master category",
+        input: mailboxInput.extend({ displayName: z.string().min(1), color: z.string().default("preset0") }),
+        output: categoryShape,
+        run: async (ctx, i) =>
+          mapCategory((await ctx.http.post(masterCategoriesPath(i.mailbox), { displayName: i.displayName, color: i.color })) as RawCategory),
+      }),
+    },
+  },
+  triggers: {
+    messageReceived: trigger.poll({
+      describe: "Fires for each new message created in an Outlook mail folder (delta-query poll)",
+      input: mailboxInput.extend({ folderId: z.string().default("inbox"), maxPageSize: z.number().int().min(1).max(100).default(25) }),
+      output: messageSummaryShape,
+      interval: { default: "1m", floor: "30s" },
+      order: "newest-first",
+      poll: (ctx, params, cursor) => pollCreatedMessages(ctx, params.mailbox, params.folderId, params.maxPageSize, cursor),
+      dedupeKey: (raw) => (raw as RawMessage).id,
+      map: (raw) => mapSummary(raw as RawMessage),
+    }),
+  },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devosurf/tesser-connectors",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.3",
   "description": "Tesser connector library — typed integrations consumed as ctx.connections.<name>.",
   "license": "Apache-2.0",
   "type": "module",
@@ -14,10 +14,10 @@
   },
   "dependencies": {
     "zod": "^4.4.3",
-    "@devosurf/tesser-sdk": "0.1.0-alpha.1"
+    "@devosurf/tesser-sdk": "0.1.0-alpha.3"
   },
   "devDependencies": {
-    "@devosurf/tesser-testing": "^0.1.0-alpha.1"
+    "@devosurf/tesser-testing": "^0.1.0-alpha.3"
   },
   "files": [
     "index.ts",

package/providers/microsoft.ts

@@ -0,0 +1,18 @@
+import type { ProviderFacts } from "@devosurf/tesser-sdk/connector";
+
+// Shared Provider for Microsoft Graph surfaces (Outlook Mail, Teams, Excel,
+// OneDrive/SharePoint). One Entra app backs the family; individual Connectors
+// contribute their own Graph scopes.
+export const microsoftProvider: ProviderFacts = {
+  id: "microsoft",
+  displayName: "Microsoft",
+  baseUrl: "https://graph.microsoft.com/v1.0",
+  docsUrl: "https://learn.microsoft.com/graph",
+  oauth2: {
+    authorizeUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+    tokenUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+    clientAuth: "body",
+    scopeSeparator: " ",
+    pkce: true,
+  },
+};