@zapier/microsoft-outlook-connector 0.0.0 → 0.1.0

package/scripts/getMe.ts

@@ -0,0 +1,42 @@
+#!/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";
+
+const inputSchema = z.object({}).strict();
+
+const outputSchema = z.object({
+  id: z.string(),
+  displayName: z.string().optional(),
+  mail: z.string().optional(),
+  userPrincipalName: z.string(),
+  jobTitle: z.string().optional(),
+  mobilePhone: z.string().optional(),
+});
+
+const definition = defineTool({
+  name: "getMe",
+  title: "Get Me",
+  description:
+    'Retrieve the signed-in user\'s profile — id, displayName, mail, and userPrincipalName. Doubles as the auth probe (a 200 confirms the connection works). Call this first to resolve "my email" before composing or filtering mail.',
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (_input, ctx) => {
+    const url = `${GRAPH_BASE}/me`;
+    const res = await outlookFetch(ctx.fetch, "getMe", url);
+    return parseGraphResponse(res);
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/getMessage.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";
+import { messageSchema } 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.",
+      ),
+    bodyContentType: z
+      .enum(["text", "html"])
+      .describe(
+        "Format for the returned body. Defaults to text (smaller, keeps visible URLs); pass html to preserve formatting.",
+      )
+      .optional(),
+    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(),
+  })
+  .strict();
+
+const outputSchema = messageSchema;
+
+const definition = defineTool({
+  name: "getMessage",
+  title: "Get Message",
+  description:
+    "Retrieve a single message by id, including its full body, recipient lists, flag, and categories. Resolve the id via listMessages first. The body is returned as plain text by default; pass bodyContentType: html for the original markup.",
+  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,
+    )}`;
+    // Body content type is a Prefer header, not a query param; default to text.
+    const res = await outlookFetch(ctx.fetch, "getMessage", url, {
+      headers: {
+        Prefer: `outlook.body-content-type="${input.bodyContentType ?? "text"}"`,
+      },
+    });
+    return parseGraphResponse(res);
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/listAttachments.ts

@@ -0,0 +1,94 @@
+#!/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 {
+  attachmentListItemSchema,
+  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.",
+      ),
+    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(),
+    limit: z
+      .number()
+      .int()
+      .gte(1)
+      .describe(
+        "Attachments 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(attachmentListItemSchema),
+  next_cursor: z
+    .string()
+    .describe("Pass as cursor to fetch the next page. Absent on the last page.")
+    .optional(),
+});
+
+const definition = defineTool({
+  name: "listAttachments",
+  title: "List Attachments",
+  description:
+    "List the attachments on a message — name, content type, size, kind, and inline flag. Resolve the messageId via listMessages first, then use getAttachment to download a specific one's bytes. A message's hasAttachments is false when it has only inline attachments, so still call this to check for them.",
+  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 path = `${mailboxRoot(input.mailbox)}/messages/${encodeURIComponent(
+        input.messageId,
+      )}/attachments`;
+      const query = buildListQuery({ limit: input.limit ?? 20 });
+      url = `${GRAPH_BASE}${path}${query}`;
+    }
+    const res = await outlookFetch(ctx.fetch, "listAttachments", url);
+    const result = toListResult<Record<string, unknown>>(await res.json());
+    return {
+      ...result,
+      items: result.items.map((item) => normalizeAttachment(item)),
+    };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/listCalendarView.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 {
+  calendarRoot,
+  GRAPH_BASE,
+  outlookFetch,
+  toListResult,
+} from "../lib/graph.ts";
+import { eventListItemSchema } from "../lib/schemas.ts";
+
+const inputSchema = z
+  .object({
+    startDateTime: z
+      .string()
+      .describe(
+        'Window start, ISO 8601 (e.g. "2026-07-01T00:00:00"). Interpreted as UTC unless it carries an offset.',
+      ),
+    endDateTime: z
+      .string()
+      .describe(
+        "Window end, ISO 8601. Interpreted as UTC unless it carries an offset.",
+      ),
+    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(),
+    calendarId: z
+      .string()
+      .describe(
+        "Target a specific calendar (id from listCalendars). Omit to use the default calendar.",
+      )
+      .optional(),
+    limit: z
+      .number()
+      .int()
+      .gte(1)
+      .describe(
+        "Events per page. Defaults to 20 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(eventListItemSchema),
+  next_cursor: z
+    .string()
+    .describe("Pass as cursor to fetch the next page. Absent on the last page.")
+    .optional(),
+});
+
+const definition = defineTool({
+  name: "listCalendarView",
+  title: "List Calendar View",
+  description:
+    'The primary "what\'s on my calendar" tool: list everything occurring between startDateTime and endDateTime, expanding recurring series into their individual occurrences. Targets the default calendar unless calendarId is set.',
+  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 {
+      // calendarView takes literal startDateTime/endDateTime params (not
+      // $-prefixed), plus the standard $top page size.
+      const sp = new URLSearchParams();
+      sp.set("startDateTime", input.startDateTime);
+      sp.set("endDateTime", input.endDateTime);
+      sp.set("$top", String(input.limit ?? 20));
+      url = `${GRAPH_BASE}${calendarRoot(input.mailbox, input.calendarId)}/calendarView?${sp.toString()}`;
+    }
+    const res = await outlookFetch(ctx.fetch, "listCalendarView", url);
+    return toListResult(await res.json());
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/listCalendars.ts

@@ -0,0 +1,85 @@
+#!/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({
+    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(
+        "Calendars per page. Defaults to 20 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(
+    z.object({
+      id: z.string(),
+      name: z.string(),
+      isDefaultCalendar: z.boolean().optional(),
+      canEdit: z.boolean().optional(),
+    }),
+  ),
+  next_cursor: z
+    .string()
+    .describe("Pass as cursor to fetch the next page. Absent on the last page.")
+    .optional(),
+});
+
+const definition = defineTool({
+  name: "listCalendars",
+  title: "List Calendars",
+  description:
+    "List the available calendars in a mailbox. The entry point for resolving a calendarId to pass to the event tools (listEvents, listCalendarView, createEvent, ...); omit calendarId on those tools to use the default calendar.",
+  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 query = buildListQuery({ limit: input.limit ?? 20 });
+      url = `${GRAPH_BASE}${mailboxRoot(input.mailbox)}/calendars${query}`;
+    }
+    const res = await outlookFetch(ctx.fetch, "listCalendars", url);
+    return toListResult(await res.json());
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/listCategories.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, stripNullsDeep } from "../lib/graph.ts";
+
+const inputSchema = z.object({}).strict();
+
+const outputSchema = z.object({
+  items: z.array(
+    z.object({
+      id: z.string().optional(),
+      displayName: z.string(),
+      color: z
+        .string()
+        .describe('Preset color name, e.g. "preset0".')
+        .optional(),
+    }),
+  ),
+});
+
+const definition = defineTool({
+  name: "listCategories",
+  title: "List Categories",
+  description:
+    "List the signed-in user's category names and colors. A discovery tool for the valid category names passed to updateMessage or createEvent — a category's color comes from the user's master list (you apply a category by its displayName). Only your own categories (no mailbox option).",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (_input, ctx) => {
+    // masterCategories is not paginated (no @odata.nextLink), so read the
+    // `value` array directly instead of going through toListResult.
+    const url = `${GRAPH_BASE}/me/outlook/masterCategories`;
+    const res = await outlookFetch(ctx.fetch, "listCategories", url);
+    const body = (await res.json()) as { value?: unknown[] };
+    return { items: (body.value ?? []).map((c) => stripNullsDeep(c)) };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/listContacts.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 {
+  buildListQuery,
+  GRAPH_BASE,
+  outlookFetch,
+  toListResult,
+} from "../lib/graph.ts";
+import { contactSchema } from "../lib/schemas.ts";
+
+const inputSchema = z
+  .object({
+    filter: z
+      .string()
+      .describe(
+        "OData $filter predicate. Only the email-match form is supported server-side, e.g. \"emailAddresses/any(a:a/address eq 'jane@contoso.com')\". Name search is NOT filterable — list and filter the returned results client-side instead. Omit to list all contacts.",
+      )
+      .optional(),
+    limit: z
+      .number()
+      .int()
+      .gte(1)
+      .describe(
+        "Contacts per page. Defaults to 20 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(contactSchema),
+  next_cursor: z
+    .string()
+    .describe("Pass as cursor to fetch the next page. Absent on the last page.")
+    .optional(),
+});
+
+const definition = defineTool({
+  name: "listContacts",
+  title: "List Contacts",
+  description:
+    "List or search the user's personal contacts. Use filter to match by email, e.g. \"emailAddresses/any(a:a/address eq 'jane@contoso.com')\"; name search isn't filterable server-side, so list and match the returned results yourself. The entry point for resolving a contact id before getContact/updateContact/deleteContact.",
+  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 query = buildListQuery({
+        limit: input.limit ?? 20,
+        filter: input.filter,
+      });
+      url = `${GRAPH_BASE}/me/contacts${query}`;
+    }
+    const res = await outlookFetch(ctx.fetch, "listContacts", url);
+    return toListResult(await res.json());
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/listEvents.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  buildListQuery,
+  calendarRoot,
+  GRAPH_BASE,
+  outlookFetch,
+  toListResult,
+} from "../lib/graph.ts";
+import { eventListItemSchema } from "../lib/schemas.ts";
+
+const inputSchema = z
+  .object({
+    filter: z
+      .string()
+      .describe(
+        "OData $filter predicate for exact matches, e.g. \"subject eq 'Standup'\" or \"showAs eq 'busy'\". Omit to list all events.",
+      )
+      .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(),
+    calendarId: z
+      .string()
+      .describe(
+        "Target a specific calendar (id from listCalendars). Omit to use the default calendar.",
+      )
+      .optional(),
+    limit: z
+      .number()
+      .int()
+      .gte(1)
+      .describe(
+        "Events per page. Defaults to 20 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(eventListItemSchema),
+  next_cursor: z
+    .string()
+    .describe("Pass as cursor to fetch the next page. Absent on the last page.")
+    .optional(),
+});
+
+const definition = defineTool({
+  name: "listEvents",
+  title: "List Events",
+  description:
+    "List a calendar's events: single events plus recurring SERIES MASTERS (the recurrence definition, not expanded occurrences). Use filter for exact predicates. To see what actually occurs within a date range — including each occurrence of a recurring series — use listCalendarView instead.",
+  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 query = buildListQuery({
+        limit: input.limit ?? 20,
+        filter: input.filter,
+      });
+      url = `${GRAPH_BASE}${calendarRoot(input.mailbox, input.calendarId)}/events${query}`;
+    }
+    const res = await outlookFetch(ctx.fetch, "listEvents", url);
+    return toListResult(await res.json());
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });