@zapier/microsoft-outlook-connector 0.0.0 → 0.1.0

package/scripts/createDraft.ts

@@ -0,0 +1,71 @@
+#!/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 {
+  outgoingMessageSchema,
+  recipientSchema,
+  toGraphOutgoingMessage,
+} from "../lib/schemas.ts";
+
+const inputSchema = z
+  .object({
+    ...outgoingMessageSchema.shape,
+    mailbox: z
+      .string()
+      .describe(
+        "Shared-mailbox address (UPN/email) to draft in instead of your own, e.g. team@contoso.com. Requires Send-as/Send-on-behalf delegation. Omit to draft in your own mailbox.",
+      )
+      .optional(),
+  })
+  .strict();
+
+const outputSchema = z.object({
+  id: z.string().describe("Draft id — pass to sendDraft to send it later."),
+  subject: z.string(),
+  isDraft: z.boolean(),
+  bodyPreview: z
+    .string()
+    .optional()
+    .describe(
+      "First ~255 chars of the body; use getMessage for the full body.",
+    ),
+  toRecipients: z.array(recipientSchema).optional(),
+  webLink: z.string().optional(),
+});
+
+const definition = defineTool({
+  name: "createDraft",
+  title: "Create Draft",
+  description:
+    "Compose an email and save it as a draft without sending. Returns the draft's id — the id-bearing path: pair with sendDraft when you need to reference or send the message later, or leave the draft for a human to review. Use sendMail to compose and send in one step (no id returned).",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (input, ctx) => {
+    const { mailbox, ...message } = input;
+    const url = `${GRAPH_BASE}${mailboxRoot(mailbox)}/messages`;
+    const res = await outlookFetch(ctx.fetch, "createDraft", url, {
+      method: "POST",
+      body: JSON.stringify(toGraphOutgoingMessage(message)),
+    });
+    return parseGraphResponse(res);
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/createEvent.ts

@@ -0,0 +1,61 @@
+#!/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({
+    ...outgoingEventSchema.shape,
+    mailbox: z
+      .string()
+      .describe(
+        "Shared-mailbox address (UPN/email) to create the event in 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: "createEvent",
+  title: "Create Event",
+  description:
+    "Create a calendar event. Targets the default calendar unless calendarId is set. start and end are { dateTime, timeZone } objects where dateTime is a naive local timestamp (no trailing Z or offset). For an all-day event set isAllDay with start/end at midnight in the same time zone (end is midnight of the day AFTER the last day). Set isOnlineMeeting to add a Teams online meeting.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (input, ctx) => {
+    const { mailbox, calendarId, ...event } = input;
+    const url = `${GRAPH_BASE}${calendarRoot(mailbox, calendarId)}/events`;
+    const res = await outlookFetch(ctx.fetch, "createEvent", url, {
+      method: "POST",
+      body: JSON.stringify(event),
+    });
+    return parseGraphResponse(res);
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/createMailFolder.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({
+    displayName: z.string().describe("Folder name as shown in Outlook."),
+    parentFolderId: z
+      .string()
+      .describe(
+        "Set a folder id (or well-known name from listMailFolders) to create the folder as a subfolder of it. Omit to create at the top level.",
+      )
+      .optional(),
+    mailbox: z
+      .string()
+      .describe(
+        "Shared-mailbox address (UPN/email) to create the folder in instead of your own, e.g. team@contoso.com. Requires shared-mailbox delegation. Omit for your own mailbox.",
+      )
+      .optional(),
+  })
+  .strict();
+
+const outputSchema = z.object({
+  id: z.string(),
+  displayName: z.string(),
+  parentFolderId: z.string().optional(),
+});
+
+const definition = defineTool({
+  name: "createMailFolder",
+  title: "Create Mail Folder",
+  description:
+    "Create a mail folder, returning its id. Creates a top-level folder by default, or a subfolder when parentFolderId is set (resolve the parent id via listMailFolders). Use the returned id as folderId/destinationId in other mail tools.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (input, ctx) => {
+    const root = mailboxRoot(input.mailbox);
+    const path =
+      input.parentFolderId !== undefined
+        ? `${root}/mailFolders/${encodeURIComponent(input.parentFolderId)}/childFolders`
+        : `${root}/mailFolders`;
+    const url = `${GRAPH_BASE}${path}`;
+    const res = await outlookFetch(ctx.fetch, "createMailFolder", url, {
+      method: "POST",
+      body: JSON.stringify({ displayName: input.displayName }),
+    });
+    return parseGraphResponse(res);
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/createReplyDraft.ts

@@ -0,0 +1,81 @@
+#!/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(
+        "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 to seed the draft body, above the quoted original. Plain text or HTML.",
+      )
+      .optional(),
+    replyAll: z
+      .boolean()
+      .describe(
+        "Draft a 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 draft the reply in instead of your own, e.g. team@contoso.com. Requires Send-as/Send-on-behalf delegation. Omit for your own mailbox.",
+      )
+      .optional(),
+  })
+  .strict();
+
+const outputSchema = z.object({
+  id: z
+    .string()
+    .describe("Draft reply id — edit further or pass to sendDraft."),
+  subject: z.string(),
+  isDraft: z.boolean(),
+  webLink: z.string().optional(),
+});
+
+const definition = defineTool({
+  name: "createReplyDraft",
+  title: "Create Reply Draft",
+  description:
+    "Create a draft reply (not sent), pre-populated with the original recipients and quoted body. Set replyAll to draft a reply to all original recipients (To + Cc). Returns the draft's id — review/edit it, then send with sendDraft. Resolve the message id via listMessages first; to reply and send in one step, use replyToMessage.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (input, ctx) => {
+    const action = input.replyAll ? "createReplyAll" : "createReply";
+    const url = `${GRAPH_BASE}${mailboxRoot(input.mailbox)}/messages/${encodeURIComponent(
+      input.messageId,
+    )}/${action}`;
+    const res = await outlookFetch(ctx.fetch, "createReplyDraft", url, {
+      method: "POST",
+      body: JSON.stringify(
+        input.comment !== undefined ? { comment: input.comment } : {},
+      ),
+    });
+    return parseGraphResponse(res);
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/deleteContact.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import { GRAPH_BASE, outlookFetch } from "../lib/graph.ts";
+
+const inputSchema = z
+  .object({
+    contactId: z
+      .string()
+      .describe("Contact id from listContacts. Opaque and case-sensitive."),
+  })
+  .strict();
+
+// Graph's DELETE /me/contacts/{id} returns 204 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: "deleteContact",
+  title: "Delete Contact",
+  description:
+    "Delete a personal contact by id. This cannot be undone — resolve the id via listContacts and confirm it's the right contact first.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (input, ctx) => {
+    const url = `${GRAPH_BASE}/me/contacts/${encodeURIComponent(
+      input.contactId,
+    )}`;
+    await outlookFetch(ctx.fetch, "deleteContact", url, { method: "DELETE" });
+    return { success: true as const };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/deleteEvent.ts

@@ -0,0 +1,61 @@
+#!/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 } from "../lib/graph.ts";
+
+const inputSchema = z
+  .object({
+    eventId: z
+      .string()
+      .describe(
+        "Opaque event id from listEvents, listCalendarView, or getEvent.",
+      ),
+    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();
+
+// Graph's DELETE /events/{id} returns 204 with no body — run() synthesizes a
+// success result.
+const outputSchema = z.object({
+  success: z.literal(true),
+});
+
+const definition = defineTool({
+  name: "deleteEvent",
+  title: "Delete Event",
+  description:
+    "Delete (cancel) a calendar event. For events you organize, attendees are notified of the cancellation — this is not trivially reversible.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (input, ctx) => {
+    const url = `${GRAPH_BASE}${calendarRoot(input.mailbox, input.calendarId)}/events/${encodeURIComponent(
+      input.eventId,
+    )}`;
+    await outlookFetch(ctx.fetch, "deleteEvent", url, { method: "DELETE" });
+    return { success: true as const };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/deleteMessage.ts

@@ -0,0 +1,57 @@
+#!/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(
+        "Message id from listMessages or another message tool. Opaque and case-sensitive; changes when the message is moved between folders.",
+      ),
+    mailbox: z
+      .string()
+      .describe(
+        "Shared-mailbox address (UPN/email) to delete from instead of your own. Requires shared-mailbox delegation. Omit for your own mailbox.",
+      )
+      .optional(),
+  })
+  .strict();
+
+// Graph's DELETE /messages/{id} returns 204 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: "deleteMessage",
+  title: "Delete Message",
+  description:
+    "Soft-delete a message: it moves to the Deleted Items folder and is reversible (move it back out to restore). Resolve the message id via listMessages first.",
+  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,
+    )}`;
+    await outlookFetch(ctx.fetch, "deleteMessage", url, {
+      method: "DELETE",
+    });
+    return { success: true as const };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/forwardMessage.ts

@@ -0,0 +1,75 @@
+#!/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 { recipientInputSchema } from "../lib/schemas.ts";
+
+const inputSchema = z
+  .object({
+    messageId: z
+      .string()
+      .describe(
+        "Id of the message to forward, from listMessages or getMessage. Opaque and case-sensitive; changes when the message is moved between folders.",
+      ),
+    toRecipients: z
+      .array(recipientInputSchema)
+      .min(1)
+      .describe(
+        'Who to forward the message to, e.g. [{ "emailAddress": { "address": "jane@contoso.com" } }].',
+      ),
+    comment: z
+      .string()
+      .describe(
+        "Note prepended above the forwarded original. Plain text or HTML.",
+      )
+      .optional(),
+    mailbox: z
+      .string()
+      .describe(
+        "Shared-mailbox address (UPN/email) to forward from instead of your own, e.g. team@contoso.com. Requires Send-as/Send-on-behalf delegation. Omit to forward as yourself.",
+      )
+      .optional(),
+  })
+  .strict();
+
+// Graph's POST /forward 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: "forwardMessage",
+  title: "Forward Message",
+  description:
+    "Forward a message to new recipients and send immediately, quoting the original. Returns only a success flag (202 accepted, no id). Resolve the message id via listMessages 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,
+    )}/forward`;
+    const body = {
+      toRecipients: input.toRecipients,
+      ...(input.comment !== undefined ? { comment: input.comment } : {}),
+    };
+    await outlookFetch(ctx.fetch, "forwardMessage", url, {
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+    return { success: true as const };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/getAttachment.ts

@@ -0,0 +1,60 @@
+#!/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 { attachmentSchema, normalizeAttachment } 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.",
+      ),
+    attachmentId: z.string().describe("Attachment id from listAttachments."),
+    mailbox: z
+      .string()
+      .describe(
+        "Shared-mailbox address (UPN/email) to read from instead of your own, e.g. team@contoso.com. Requires shared-mailbox delegation. Omit for your own mailbox.",
+      )
+      .optional(),
+  })
+  .strict();
+
+const outputSchema = attachmentSchema;
+
+const definition = defineTool({
+  name: "getAttachment",
+  title: "Get Attachment",
+  description:
+    "Retrieve one attachment by id, including its base64 contentBytes. Resolve the attachmentId via listAttachments first. contentBytes is present only for file attachments — item and reference attachments carry no inline bytes.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (input, ctx) => {
+    const url = `${GRAPH_BASE}${mailboxRoot(input.mailbox)}/messages/${encodeURIComponent(
+      input.messageId,
+    )}/attachments/${encodeURIComponent(input.attachmentId)}`;
+    const res = await outlookFetch(ctx.fetch, "getAttachment", url);
+    return normalizeAttachment(
+      await parseGraphResponse<Record<string, unknown>>(res),
+    );
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/getContact.ts

@@ -0,0 +1,44 @@
+#!/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 } from "../lib/schemas.ts";
+
+const inputSchema = z
+  .object({
+    contactId: z
+      .string()
+      .describe("Contact id from listContacts. Opaque and case-sensitive."),
+  })
+  .strict();
+
+const outputSchema = contactSchema;
+
+const definition = defineTool({
+  name: "getContact",
+  title: "Get Contact",
+  description:
+    "Retrieve a single personal contact by id, including names, company, email addresses, and phone numbers. Resolve the id via listContacts first. The resolver getter for updateContact.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (input, ctx) => {
+    const url = `${GRAPH_BASE}/me/contacts/${encodeURIComponent(
+      input.contactId,
+    )}`;
+    const res = await outlookFetch(ctx.fetch, "getContact", url);
+    return parseGraphResponse(res);
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/getEvent.ts

@@ -0,0 +1,63 @@
+#!/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 } from "../lib/schemas.ts";
+
+const inputSchema = z
+  .object({
+    eventId: z
+      .string()
+      .describe(
+        "Opaque event id from listEvents, listCalendarView, or getEvent.",
+      ),
+    mailbox: z
+      .string()
+      .describe(
+        "Shared-mailbox address (UPN/email) to read from 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: "getEvent",
+  title: "Get Event",
+  description:
+    "Retrieve a single calendar event by id, including attendees, body, and online-meeting details. Resolve the id via listEvents or listCalendarView first. Use this to read the current state before updateEvent (read-modify-write — e.g. fetch the attendees, append, then update).",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (input, ctx) => {
+    const url = `${GRAPH_BASE}${calendarRoot(input.mailbox, input.calendarId)}/events/${encodeURIComponent(
+      input.eventId,
+    )}`;
+    const res = await outlookFetch(ctx.fetch, "getEvent", url);
+    return parseGraphResponse(res);
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });