@zapier/microsoft-outlook-connector 0.0.0 → 0.1.0

package/scripts/listMailFolders.ts

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  buildListQuery,
+  GRAPH_BASE,
+  mailboxRoot,
+  outlookFetch,
+  toListResult,
+} from "../lib/graph.ts";
+
+const inputSchema = z
+  .object({
+    parentFolderId: z
+      .string()
+      .describe(
+        "Omit to list top-level folders. Set a folder id (from a previous call) or a well-known name (inbox, drafts, sentitems, deleteditems, archive, junkemail) to list that folder's subfolders.",
+      )
+      .optional(),
+    mailbox: z
+      .string()
+      .describe(
+        "Shared-mailbox address (UPN/email) to read instead of your own, e.g. team@contoso.com. Requires shared-mailbox delegation. Omit for your own mailbox.",
+      )
+      .optional(),
+    limit: z
+      .number()
+      .int()
+      .gte(1)
+      .describe(
+        "Folders per page. Defaults to 20 when omitted; pass a value when you need a specific number.",
+      )
+      .optional(),
+    cursor: z
+      .string()
+      .describe(
+        "Pagination cursor from a previous response's next_cursor. Omit for the first page.",
+      )
+      .optional(),
+  })
+  .strict();
+
+const outputSchema = z.object({
+  items: z.array(
+    z.object({
+      id: z.string(),
+      displayName: z.string(),
+      parentFolderId: z.string().optional(),
+      childFolderCount: z.number().optional(),
+      unreadItemCount: z.number().optional(),
+      totalItemCount: z.number().optional(),
+    }),
+  ),
+  next_cursor: z
+    .string()
+    .describe("Pass as cursor to fetch the next page. Absent on the last page.")
+    .optional(),
+});
+
+const definition = defineTool({
+  name: "listMailFolders",
+  title: "List Mail Folders",
+  description:
+    "List mail folders. Returns top-level folders by default; pass parentFolderId to list a folder's subfolders. The entry point for resolving a folder id to pass as folderId to listMessages or destinationId to moveMessage.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (input, ctx) => {
+    // `@odata.nextLink` is an opaque full URL — when paging, fetch it verbatim
+    // and skip rebuilding the path/query.
+    let url: string;
+    if (input.cursor !== undefined) {
+      url = input.cursor;
+    } else {
+      const root = mailboxRoot(input.mailbox);
+      const path =
+        input.parentFolderId !== undefined
+          ? `${root}/mailFolders/${encodeURIComponent(input.parentFolderId)}/childFolders`
+          : `${root}/mailFolders`;
+      const query = buildListQuery({ limit: input.limit ?? 20 });
+      url = `${GRAPH_BASE}${path}${query}`;
+    }
+    const res = await outlookFetch(ctx.fetch, "listMailFolders", url);
+    return toListResult(await res.json());
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/listMessages.ts

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  buildListQuery,
+  GRAPH_BASE,
+  mailboxRoot,
+  outlookFetch,
+  toListResult,
+} from "../lib/graph.ts";
+import { messageListItemSchema } from "../lib/schemas.ts";
+
+const inputSchema = z
+  .object({
+    folderId: z
+      .string()
+      .describe(
+        "Restrict to one folder: a folder id from listMailFolders, or a well-known name (inbox, drafts, sentitems, deleteditems, archive, junkemail). Omit to list across all folders.",
+      )
+      .optional(),
+    search: z
+      .string()
+      .describe(
+        'Full-text KQL search over the default from/subject/body properties, e.g. "subject:invoice from:acme". Results are sorted by the date and time sent. Omit to list newest-first.',
+      )
+      .optional(),
+    filter: z
+      .string()
+      .describe(
+        'OData $filter predicate for exact matches, e.g. "isRead eq false" or "importance eq \'high\'". Use search for free-text instead.',
+      )
+      .optional(),
+    mailbox: z
+      .string()
+      .describe(
+        "Shared-mailbox address (UPN/email) to read instead of your own, e.g. team@contoso.com. Requires shared-mailbox delegation. Omit for your own mailbox.",
+      )
+      .optional(),
+    limit: z
+      .number()
+      .int()
+      .gte(1)
+      .describe(
+        "Messages per page. Defaults to 10 when omitted; pass a value when you need a specific number of results.",
+      )
+      .optional(),
+    cursor: z
+      .string()
+      .describe(
+        "Pagination cursor from a previous response's next_cursor. Omit for the first page.",
+      )
+      .optional(),
+  })
+  .strict();
+
+const outputSchema = z.object({
+  items: z.array(messageListItemSchema),
+  next_cursor: z
+    .string()
+    .describe("Pass as cursor to fetch the next page. Absent on the last page.")
+    .optional(),
+});
+
+const definition = defineTool({
+  name: "listMessages",
+  title: "List Messages",
+  description:
+    'Search or list mailbox messages. Listing is newest-first; search results (KQL, e.g. "subject:invoice from:acme") are ordered by sent date, not recency. Scope with folderId; exact-match with filter. The entry point for resolving a message id before getMessage/updateMessage/moveMessage.',
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (input, ctx) => {
+    // `@odata.nextLink` is an opaque full URL — when paging, fetch it verbatim
+    // and skip rebuilding the path/query.
+    let url: string;
+    if (input.cursor !== undefined) {
+      url = input.cursor;
+    } else {
+      const root = mailboxRoot(input.mailbox);
+      const path =
+        input.folderId !== undefined
+          ? `${root}/mailFolders/${encodeURIComponent(input.folderId)}/messages`
+          : `${root}/messages`;
+      const query = buildListQuery({
+        limit: input.limit ?? 10,
+        search: input.search,
+        filter: input.filter,
+      });
+      url = `${GRAPH_BASE}${path}${query}`;
+    }
+    const res = await outlookFetch(ctx.fetch, "listMessages", url);
+    return toListResult(await res.json());
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/moveMessage.ts

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  GRAPH_BASE,
+  mailboxRoot,
+  outlookFetch,
+  parseGraphResponse,
+} from "../lib/graph.ts";
+
+const inputSchema = z
+  .object({
+    messageId: z
+      .string()
+      .describe(
+        "Message id from listMessages or another message tool. Opaque and case-sensitive; changes when the message is moved between folders.",
+      ),
+    destinationId: z
+      .string()
+      .describe(
+        "Target folder: a folder id from listMailFolders, or a well-known name (inbox, archive, deleteditems, junkemail, drafts, sentitems).",
+      ),
+    mailbox: z
+      .string()
+      .describe(
+        "Shared-mailbox address (UPN/email) to move within instead of your own. Requires shared-mailbox delegation. Omit for your own mailbox.",
+      )
+      .optional(),
+  })
+  .strict();
+
+const outputSchema = z.object({
+  id: z.string(),
+  parentFolderId: z.string(),
+  subject: z.string(),
+});
+
+const definition = defineTool({
+  name: "moveMessage",
+  title: "Move Message",
+  description:
+    "Move a message into another folder. Resolve the message id via listMessages first. IMPORTANT: the message id CHANGES after a move — use the id from this response for any follow-up call, not the id you passed in.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (input, ctx) => {
+    const url = `${GRAPH_BASE}${mailboxRoot(input.mailbox)}/messages/${encodeURIComponent(
+      input.messageId,
+    )}/move`;
+    const res = await outlookFetch(ctx.fetch, "moveMessage", url, {
+      method: "POST",
+      body: JSON.stringify({ destinationId: input.destinationId }),
+    });
+    return parseGraphResponse(res);
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/replyToMessage.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import { GRAPH_BASE, mailboxRoot, outlookFetch } from "../lib/graph.ts";
+
+const inputSchema = z
+  .object({
+    messageId: z
+      .string()
+      .describe(
+        "Id of the message to reply to, from listMessages or getMessage. Opaque and case-sensitive; changes when the message is moved between folders.",
+      ),
+    comment: z
+      .string()
+      .describe(
+        "Reply text prepended above the quoted original. Plain text or HTML. Omit to send an empty-bodied reply.",
+      )
+      .optional(),
+    replyAll: z
+      .boolean()
+      .describe(
+        "Reply to all original recipients (To + Cc) instead of just the sender. Defaults to false.",
+      )
+      .optional(),
+    mailbox: z
+      .string()
+      .describe(
+        "Shared-mailbox address (UPN/email) to reply from instead of your own, e.g. team@contoso.com. Requires Send-as/Send-on-behalf delegation. Omit to reply as yourself.",
+      )
+      .optional(),
+  })
+  .strict();
+
+// Graph's POST /reply and /replyAll return 202 with no body, so there is
+// nothing to echo back — run() synthesizes a success result.
+const outputSchema = z.object({
+  success: z.literal(true),
+});
+
+const definition = defineTool({
+  name: "replyToMessage",
+  title: "Reply To Message",
+  description:
+    "Reply to a message and send immediately, quoting the original. Set replyAll to reply to all original recipients (To + Cc). Returns only a success flag (202 accepted, no id). Resolve the message id via listMessages first; to draft a reply for review instead, use createReplyDraft.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (input, ctx) => {
+    const action = input.replyAll ? "replyAll" : "reply";
+    const url = `${GRAPH_BASE}${mailboxRoot(input.mailbox)}/messages/${encodeURIComponent(
+      input.messageId,
+    )}/${action}`;
+    await outlookFetch(ctx.fetch, "replyToMessage", url, {
+      method: "POST",
+      body: JSON.stringify(
+        input.comment !== undefined ? { comment: input.comment } : {},
+      ),
+    });
+    return { success: true as const };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/sendDraft.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import { GRAPH_BASE, mailboxRoot, outlookFetch } from "../lib/graph.ts";
+
+const inputSchema = z
+  .object({
+    messageId: z
+      .string()
+      .describe(
+        "Draft id from createDraft. Opaque and case-sensitive; the id is dead once the draft is sent.",
+      ),
+    mailbox: z
+      .string()
+      .describe(
+        "Shared-mailbox address (UPN/email) the draft lives in instead of your own, e.g. team@contoso.com. Requires Send-as/Send-on-behalf delegation. Omit for your own mailbox.",
+      )
+      .optional(),
+  })
+  .strict();
+
+// Graph's POST /messages/{id}/send returns 202 with no body, so there is
+// nothing to echo back — run() synthesizes a success result.
+const outputSchema = z.object({
+  success: z.literal(true),
+});
+
+const definition = defineTool({
+  name: "sendDraft",
+  title: "Send Draft",
+  description:
+    "Send a draft email created by createDraft. Returns only a success flag (the send is accepted asynchronously, and 202 ≠ delivered); the draft id is dead after sending. Resolve the draft id from createDraft first.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (input, ctx) => {
+    const url = `${GRAPH_BASE}${mailboxRoot(input.mailbox)}/messages/${encodeURIComponent(
+      input.messageId,
+    )}/send`;
+    await outlookFetch(ctx.fetch, "sendDraft", url, { method: "POST" });
+    return { success: true as const };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/sendMail.ts

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import { GRAPH_BASE, mailboxRoot, outlookFetch } from "../lib/graph.ts";
+import {
+  outgoingMessageSchema,
+  toGraphOutgoingMessage,
+} from "../lib/schemas.ts";
+
+const inputSchema = z
+  .object({
+    message: outgoingMessageSchema.describe(
+      "The email to send. subject and toRecipients are required.",
+    ),
+    saveToSentItems: z
+      .boolean()
+      .describe("Keep a copy in Sent Items. Defaults to true.")
+      .optional(),
+    mailbox: z
+      .string()
+      .describe(
+        "Shared-mailbox address (UPN/email) to send as instead of your own, e.g. team@contoso.com. Requires Send-as/Send-on-behalf delegation. Omit to send as yourself.",
+      )
+      .optional(),
+  })
+  .strict();
+
+// Graph's POST /sendMail returns 202 with no body and no message id, so there
+// is nothing to echo back — run() synthesizes a success result.
+const outputSchema = z.object({
+  success: z.literal(true),
+});
+
+const definition = defineTool({
+  name: "sendMail",
+  title: "Send Mail",
+  description:
+    "Compose and send an email in one step. Returns only a success flag — the send is accepted asynchronously with no message id (and 202 ≠ delivered). When you need the sent message's id, use createDraft then sendDraft instead.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (input, ctx) => {
+    const url = `${GRAPH_BASE}${mailboxRoot(input.mailbox)}/sendMail`;
+    const body: Record<string, unknown> = {
+      message: toGraphOutgoingMessage(input.message),
+    };
+    if (input.saveToSentItems !== undefined) {
+      body.saveToSentItems = input.saveToSentItems;
+    }
+    await outlookFetch(ctx.fetch, "sendMail", url, {
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+    return { success: true as const };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/updateContact.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import { GRAPH_BASE, outlookFetch, parseGraphResponse } from "../lib/graph.ts";
+import { contactSchema, outgoingContactSchema } from "../lib/schemas.ts";
+
+const inputSchema = z
+  .object({
+    contactId: z
+      .string()
+      .describe("Contact id from listContacts. Opaque and case-sensitive."),
+    ...outgoingContactSchema.shape,
+  })
+  .strict();
+
+const outputSchema = contactSchema;
+
+const definition = defineTool({
+  name: "updateContact",
+  title: "Update Contact",
+  description:
+    "Update fields on a personal contact. Set only the fields you want to change. Array fields (emailAddresses, businessPhones) REPLACE the existing values — read current via getContact, merge, then update.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (input, ctx) => {
+    const { contactId, ...patch } = input;
+    const url = `${GRAPH_BASE}/me/contacts/${encodeURIComponent(contactId)}`;
+    // undefined keys are dropped by JSON.stringify, so only supplied fields
+    // are sent in the PATCH body.
+    const res = await outlookFetch(ctx.fetch, "updateContact", url, {
+      method: "PATCH",
+      body: JSON.stringify(patch),
+    });
+    return parseGraphResponse(res);
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/updateEvent.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  calendarRoot,
+  GRAPH_BASE,
+  outlookFetch,
+  parseGraphResponse,
+} from "../lib/graph.ts";
+import { eventSchema, outgoingEventSchema } from "../lib/schemas.ts";
+
+const inputSchema = z
+  .object({
+    eventId: z
+      .string()
+      .describe(
+        "Opaque event id from listEvents, listCalendarView, or getEvent.",
+      ),
+    ...outgoingEventSchema.partial().shape,
+    mailbox: z
+      .string()
+      .describe(
+        "Shared-mailbox address (UPN/email) holding the event instead of your own. Requires shared-mailbox delegation. Omit for your own mailbox.",
+      )
+      .optional(),
+    calendarId: z
+      .string()
+      .describe(
+        "Target a specific calendar (id from listCalendars). Omit to use the default calendar.",
+      )
+      .optional(),
+  })
+  .strict();
+
+const outputSchema = eventSchema;
+
+const definition = defineTool({
+  name: "updateEvent",
+  title: "Update Event",
+  description:
+    "Update a calendar event — change subject, time, location, body, attendees, or categories. Set only the fields you want to change. The attendees array REPLACES the existing list, so read the current attendees via getEvent, append, then update.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (input, ctx) => {
+    const { eventId, mailbox, calendarId, ...patch } = input;
+    const url = `${GRAPH_BASE}${calendarRoot(mailbox, calendarId)}/events/${encodeURIComponent(
+      eventId,
+    )}`;
+    // JSON.stringify drops undefined keys, so only the provided fields are sent.
+    const res = await outlookFetch(ctx.fetch, "updateEvent", url, {
+      method: "PATCH",
+      body: JSON.stringify(patch),
+    });
+    return parseGraphResponse(res);
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/updateMessage.ts

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  GRAPH_BASE,
+  mailboxRoot,
+  outlookFetch,
+  parseGraphResponse,
+} from "../lib/graph.ts";
+import {
+  dateTimeTimeZoneInputSchema,
+  followupFlagSchema,
+} from "../lib/schemas.ts";
+
+const inputSchema = z
+  .object({
+    messageId: z
+      .string()
+      .describe(
+        "Message id from listMessages or another message tool. Opaque and case-sensitive; changes when the message is moved between folders.",
+      ),
+    isRead: z
+      .boolean()
+      .describe("Mark the message read (true) or unread (false).")
+      .optional(),
+    importance: z
+      .enum(["low", "normal", "high"])
+      .describe("Importance level.")
+      .optional(),
+    categories: z
+      .array(z.string())
+      .describe(
+        "Category names to assign. REPLACES the existing set — read the current categories via getMessage and include them if you want to append rather than overwrite.",
+      )
+      .optional(),
+    flag: z
+      .strictObject({
+        flagStatus: z
+          .enum(["notFlagged", "flagged", "complete"])
+          .describe("Follow-up flag state."),
+        startDateTime: dateTimeTimeZoneInputSchema.optional(),
+        dueDateTime: dateTimeTimeZoneInputSchema.optional(),
+      })
+      .describe("Follow-up flag to set on the message.")
+      .optional(),
+    mailbox: z
+      .string()
+      .describe(
+        "Shared-mailbox address (UPN/email) to update instead of your own. Requires shared-mailbox delegation. Omit for your own mailbox.",
+      )
+      .optional(),
+  })
+  .strict();
+
+const outputSchema = z.object({
+  id: z.string(),
+  subject: z.string(),
+  isRead: z.boolean(),
+  importance: z.string().optional(),
+  categories: z.array(z.string()).optional(),
+  flag: followupFlagSchema.optional(),
+});
+
+const definition = defineTool({
+  name: "updateMessage",
+  title: "Update Message",
+  description:
+    "Update a message's state — mark read/unread, change importance, replace its categories, or set a follow-up flag. Set only the fields you want to change; everything else is left untouched. Resolve the message id via listMessages first. Subject/body are editable only on drafts.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (input, ctx) => {
+    const url = `${GRAPH_BASE}${mailboxRoot(input.mailbox)}/messages/${encodeURIComponent(
+      input.messageId,
+    )}`;
+    const body: Record<string, unknown> = {};
+    if (input.isRead !== undefined) body.isRead = input.isRead;
+    if (input.importance !== undefined) body.importance = input.importance;
+    if (input.categories !== undefined) body.categories = input.categories;
+    if (input.flag !== undefined) body.flag = input.flag;
+    const res = await outlookFetch(ctx.fetch, "updateMessage", url, {
+      method: "PATCH",
+      body: JSON.stringify(body),
+    });
+    return parseGraphResponse(res);
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });