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

package/README.md

@@ -3,6 +3,8 @@
 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`, 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/manifest.json

@@ -608,7 +608,12 @@
             "offline_access",
             "Mail.Read",
             "Mail.ReadWrite",
-            "Mail.Send"
+            "Mail.Send",
+            "Mail.Read.Shared",
+            "Mail.ReadWrite.Shared",
+            "Mail.Send.Shared",
+            "MailboxSettings.Read",
+            "MailboxSettings.ReadWrite"
           ],
           "flow": "auth_code",
           "provider": "microsoft"
@@ -621,6 +626,12 @@
           "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",
@@ -645,6 +656,24 @@
           "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",
@@ -692,6 +721,18 @@
           "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": [

package/outlook-mail/index.ts

@@ -77,11 +77,13 @@ const attachmentShape = z.object({
   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 sendOrDraftInput = z.object({
+const composeInput = mailboxInput.extend({
   to: recipientsInput,
   subject: z.string(),
   text: z.string(),
@@ -89,11 +91,14 @@ const sendOrDraftInput = z.object({
   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 updateDraftInput = z.object({
+const sendInput = composeInput.extend({ saveToSentItems: z.boolean().optional() });
+
+const updateDraftInput = mailboxInput.extend({
   id: z.string().min(1),
   to: recipientsInput.optional(),
   subject: z.string().optional(),
@@ -102,6 +107,7 @@ const updateDraftInput = z.object({
   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(),
 });
@@ -148,6 +154,8 @@ type RawAttachment = {
   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;
@@ -225,13 +233,17 @@ function mapAttachmentDetail(raw: RawAttachment): z.infer<typeof attachmentDetai
   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 sendOrDraftInput>): Record<string, unknown> {
+function messagePayload(input: z.infer<typeof composeInput>): Record<string, unknown> {
   return {
     subject: input.subject,
     body: { contentType: input.html === true ? "HTML" : "Text", content: input.text },
@@ -239,6 +251,7 @@ function messagePayload(input: z.infer<typeof sendOrDraftInput>): Record<string,
     ...(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 } : {}),
   };
@@ -252,17 +265,26 @@ function draftPatch(input: z.infer<typeof updateDraftInput>): Record<string, unk
     ...(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 messagePath(id: string): string {
-  return `/me/messages/${encodeURIComponent(id)}`;
+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 folderMessagesPath(folderId: string): string {
-  return `/me/mailFolders/${encodeURIComponent(folderId)}/messages`;
+function masterCategoriesPath(mailbox?: string): string {
+  return `${mailboxRoot(mailbox)}/outlook/masterCategories`;
 }
 
 async function listCollection<T>(
@@ -273,7 +295,7 @@ async function listCollection<T>(
 ): Promise<T[]> {
   const out: T[] = [];
   let path = firstPath;
-  for (let page = 0; page < 20 && out.length < limit; page++) {
+  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);
@@ -283,37 +305,80 @@ async function listCollection<T>(
   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?: string }> {
-  const items: RawMessage[] = [];
-  let path = typeof cursor === "string" && cursor.length > 0 ? cursor : `${folderMessagesPath(folderId)}/delta`;
-  for (let page = 0; page < 20; page++) {
-    const first = page === 0 && !(typeof cursor === "string" && cursor.length > 0);
-    const res = (await ctx.http.get(path, {
-      ...(first
-        ? {
-            query: {
-              changeType: "created",
-              $select: SUMMARY_SELECT,
-              $orderby: "receivedDateTime desc",
-              $top: maxPageSize,
-            },
-          }
-        : {}),
-      headers: { Prefer: `odata.maxpagesize=${maxPageSize}` },
-    })) as GraphCollection<RawMessage>;
-    items.push(...(res.value ?? []).filter((m) => m["@removed"] === undefined));
-    if (res["@odata.deltaLink"] !== undefined) {
-      return { items, nextCursor: res["@odata.deltaLink"] };
-    }
-    if (res["@odata.nextLink"] === undefined) return { items };
-    path = res["@odata.nextLink"];
+): 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 },
+    };
   }
-  throw new RetryableError(`microsoft graph delta pagination exceeded safety cap for ${folderMessagesPath(folderId)}`);
+  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 {
@@ -329,7 +394,17 @@ export default defineConnector({
   baseUrl: "https://graph.microsoft.com/v1.0",
   auth: oauth2({
     provider: "microsoft",
-    scopes: ["offline_access", "Mail.Read", "Mail.ReadWrite", "Mail.Send"],
+    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",
@@ -352,6 +427,22 @@ export default defineConnector({
         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",
@@ -390,6 +481,48 @@ export default defineConnector({
       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",
@@ -490,6 +623,8 @@ export default defineConnector({
         isHidden: false,
       },
     ],
+    "categories.list": [{ id: "cat1", displayName: "Support", color: "preset0" }],
+    "categories.create": { id: "cat2", displayName: "Escalated", color: "preset1" },
     "trigger:messageReceived": {
       id: "AAMkAD3",
       conversationId: "AAQkAD3",
@@ -509,7 +644,7 @@ export default defineConnector({
     messages: {
       list: action({
         describe: "List messages in a folder using Microsoft Graph's stable mapped shape",
-        input: z.object({
+        input: mailboxInput.extend({
           folderId: z.string().default("inbox"),
           filter: z.string().optional(),
           maxResults: z.number().int().min(1).max(250).default(25),
@@ -519,7 +654,7 @@ export default defineConnector({
         run: async (ctx, i) => {
           const raw = await listCollection<RawMessage>(
             ctx,
-            folderMessagesPath(i.folderId),
+            folderMessagesPath(i.folderId, i.mailbox),
             {
               $select: SUMMARY_SELECT,
               $orderby: "receivedDateTime desc",
@@ -531,9 +666,33 @@ export default defineConnector({
           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: z.object({
+        input: mailboxInput.extend({
           id: z.string().min(1),
           bodyContentType: bodyContentTypeInput,
           allowUnsafeHtml: z.boolean().optional(),
@@ -541,7 +700,7 @@ export default defineConnector({
         output: messageDetailShape,
         safety: "read",
         run: async (ctx, i) => {
-          const raw = (await ctx.http.get(messagePath(i.id), {
+          const raw = (await ctx.http.get(messagePath(i.id, i.mailbox), {
             query: { $select: DETAIL_SELECT },
             headers: { Prefer: preferBody(i.bodyContentType, i.allowUnsafeHtml) },
           })) as RawMessage;
@@ -550,23 +709,26 @@ export default defineConnector({
       }),
       send: action({
         describe: "Send a new email using Outlook Mail (not idempotent; creates Sent Items mail)",
-        input: sendOrDraftInput,
+        input: sendInput,
         output: z.object({ accepted: z.boolean() }),
         run: async (ctx, i) => {
-          await ctx.http.post("/me/sendMail", { message: messagePayload(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: z.object({
+        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)}/reply`, {
+          await ctx.http.post(`${messagePath(i.id, i.mailbox)}/reply`, {
             ...(i.comment !== undefined ? { comment: i.comment } : {}),
             ...(i.to !== undefined ? { message: { toRecipients: recipientObjects(i.to) } } : {}),
           });
@@ -575,37 +737,68 @@ export default defineConnector({
       }),
       markRead: action({
         describe: "Mark a message read (sets isRead=true)",
-        input: z.object({ id: z.string().min(1) }),
+        input: mailboxInput.extend({ id: z.string().min(1) }),
         output: messageSummaryShape,
         retrySafe: true,
-        run: async (ctx, i) => mapSummary((await ctx.http.patch(messagePath(i.id), { isRead: true })) as RawMessage),
+        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: z.object({ id: z.string().min(1), destinationId: z.string().min(1) }),
+        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)}/move`, { destinationId: i.destinationId })) as RawMessage),
+          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: z.object({ messageId: z.string().min(1) }),
+          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)}/attachments`)) as GraphCollection<RawAttachment>;
+            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: z.object({ messageId: z.string().min(1), id: z.string().min(1) }),
+          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)}/attachments/${encodeURIComponent(i.id)}`)) as RawAttachment,
+              (await ctx.http.get(`${messagePath(i.messageId, i.mailbox)}/attachments/${encodeURIComponent(i.id)}`)) as RawAttachment,
             ),
         }),
       },
@@ -613,13 +806,13 @@ export default defineConnector({
     drafts: {
       create: action({
         describe: "Create a new draft message for human review",
-        input: sendOrDraftInput,
+        input: composeInput,
         output: messageDetailShape,
-        run: async (ctx, i) => mapDetail((await ctx.http.post("/me/messages", messagePayload(i))) as RawMessage),
+        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: z.object({
+        input: mailboxInput.extend({
           messageId: z.string().min(1),
           comment: z.string().optional(),
           text: z.string().optional(),
@@ -636,7 +829,7 @@ export default defineConnector({
               : i.comment !== undefined
                 ? { comment: i.comment }
                 : undefined;
-          return mapDetail((await ctx.http.post(`${messagePath(i.messageId)}/createReply`, body)) as RawMessage);
+          return mapDetail((await ctx.http.post(`${messagePath(i.messageId, i.mailbox)}/createReply`, body)) as RawMessage);
         },
       }),
       update: action({
@@ -644,14 +837,14 @@ export default defineConnector({
         input: updateDraftInput,
         output: messageDetailShape,
         retrySafe: true,
-        run: async (ctx, i) => mapDetail((await ctx.http.patch(messagePath(i.id), draftPatch(i))) as RawMessage),
+        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: z.object({ id: z.string().min(1) }),
+        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)}/send`);
+          await ctx.http.post(`${messagePath(i.id, i.mailbox)}/send`);
           return { accepted: true };
         },
       }),
@@ -659,13 +852,13 @@ export default defineConnector({
     mailFolders: {
       list: action({
         describe: "List root mail folders (well-known folders like inbox, archive, deleteditems can be used directly)",
-        input: z.object({ includeHiddenFolders: z.boolean().default(false), maxResults: z.number().int().min(1).max(250).default(100) }),
+        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,
-            "/me/mailFolders",
+            `${mailboxRoot(i.mailbox)}/mailFolders`,
             { includeHiddenFolders: i.includeHiddenFolders, $top: Math.min(i.maxResults, 100) },
             i.maxResults,
           );
@@ -673,15 +866,34 @@ export default defineConnector({
         },
       }),
     },
+    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: z.object({ folderId: z.string().default("inbox"), maxPageSize: z.number().int().min(1).max(100).default(25) }),
+      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.folderId, params.maxPageSize, cursor),
+      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.2",
+  "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.2"
+    "@devosurf/tesser-sdk": "0.1.0-alpha.3"
   },
   "devDependencies": {
-    "@devosurf/tesser-testing": "^0.1.0-alpha.2"
+    "@devosurf/tesser-testing": "^0.1.0-alpha.3"
   },
   "files": [
     "index.ts",