fix(outlook): connection scopes, sync reliability, and rate-limit retries (#339)

* Connection works

* Unread connected to Outlook

---------

Co-authored-by: TobinBraun <your.email@example.com>

Author: TobinBraun

connectors/outlook/src/calendar/channels.ts

@@ -8,7 +8,7 @@ import { GraphApi } from "./graph-api";
 // ---------------------------------------------------------------------------
 
 export const OUTLOOK_CALENDAR_SCOPE =
-  "https://graph.microsoft.com/calendars.readwrite";
+  "https://graph.microsoft.com/Calendars.ReadWrite";
 
 // ---------------------------------------------------------------------------
 // Calendar type

connectors/outlook/src/calendar/graph-api.ts

@@ -117,19 +117,27 @@ export type OutlookEvent = {
 
 export type SyncState = {
   calendarId: string;
-  state?: string; // deltaToken or deltaLink
+  state?: string; // nextLink (listing mode) or deltaToken/deltaLink (delta mode)
   more?: boolean;
   min?: Date;
   max?: Date;
   sequence?: number;
   /**
    * Two-pass initial sync phase. `"quick"` walks `timeMin = now` to
-   * front-load upcoming meetings; `"full"` walks the 2-year historical
-   * backfill afterwards. Both phases share one sync lock; the
-   * quick→full transition swaps state without releasing. Absent for
-   * incremental syncs.
+   * front-load upcoming meetings; `"full"` walks the full event history
+   * afterwards to establish a real delta cursor (see `mode`). Both phases
+   * share one sync lock; the quick→full transition swaps state without
+   * releasing. Absent for incremental syncs.
    */
   phase?: "quick" | "full";
+  /**
+   * Which Graph resource `state` continues. Microsoft's `/events/delta`
+   * resource ("SyncEvents") rejects `$filter`/`$orderby`/`$select`/`$expand`/
+   * `$search` entirely — so any request bounded by `min`/`max` must use a
+   * plain, non-delta `/events` listing (`"listing"`) instead of the real
+   * delta chain (`"delta"`), which only an unfiltered request may use.
+   */
+  mode?: "listing" | "delta";
 };
 
 /**
@@ -139,7 +147,12 @@ export class GraphApi {
   constructor(public accessToken: string) {}
 
   /**
-   * Make a request to Microsoft Graph API
+   * Make a request to Microsoft Graph API. Retries once on 429/503, honoring
+   * a `Retry-After` header (seconds), capped at 15s — matches the retry
+   * behavior already in GraphMailApi.call (mail/graph-mail-api.ts). Without
+   * this, a transient rate limit during composeChannels (mail + calendar
+   * fetching channels concurrently at connect time) surfaces as a hard
+   * connect-time failure instead of a brief, self-healing delay.
    */
   public async call(
     method: string,
@@ -155,39 +168,52 @@ export class GraphApi {
       ...(body ? { "Content-Type": "application/json" } : {}),
     };
 
-    const response = await fetch(url + query, {
-      method,
-      headers,
-      ...(body ? { body: JSON.stringify(body) } : {}),
-    });
-
-    switch (response.status) {
-      case 400:
-        const responseBody = await response.json();
-        throw new Error("Invalid request", { cause: responseBody });
-      case 401:
-        throw new Error("Authentication failed - token may be expired");
-      case 403:
-        throw new Error("Access denied - insufficient permissions");
-      case 404:
-        return null;
-      case 410:
-        // Gone - delta token expired, need full sync
-        return null;
-      case 429:
-        throw new Error("Rate limit exceeded - too many requests");
-      case 200:
-      case 201:
-      case 204:
-        if (response.status === 204) return {}; // No content
-        return await response.json();
-      case 500:
-      case 502:
-      case 503:
-      case 504:
-        throw new Error(`Server error: ${response.status}`);
-      default:
-        throw new Error(await response.text());
+    for (let attempt = 0; ; attempt++) {
+      const response = await fetch(url + query, {
+        method,
+        headers,
+        ...(body ? { body: JSON.stringify(body) } : {}),
+      });
+
+      if (
+        (response.status === 429 || response.status === 503) &&
+        attempt === 0
+      ) {
+        const retryAfter = Number(response.headers.get("Retry-After") ?? "2");
+        await new Promise((r) =>
+          setTimeout(r, Math.min(isNaN(retryAfter) ? 2 : retryAfter, 15) * 1000)
+        );
+        continue;
+      }
+
+      switch (response.status) {
+        case 400:
+          const responseBody = await response.json();
+          throw new Error("Invalid request", { cause: responseBody });
+        case 401:
+          throw new Error("Authentication failed - token may be expired");
+        case 403:
+          throw new Error("Access denied - insufficient permissions");
+        case 404:
+          return null;
+        case 410:
+          // Gone - delta token expired, need full sync
+          return null;
+        case 429:
+          throw new Error("Rate limit exceeded - too many requests");
+        case 200:
+        case 201:
+        case 204:
+          if (response.status === 204) return {}; // No content
+          return await response.json();
+        case 500:
+        case 502:
+        case 503:
+        case 504:
+          throw new Error(`Server error: ${response.status}`);
+        default:
+          throw new Error(await response.text());
+      }
     }
   }
 
@@ -599,7 +625,15 @@ export function transformOutlookEvent(
 }
 
 /**
- * Sync calendar events using Microsoft Graph delta query
+ * Sync calendar events using Microsoft Graph.
+ *
+ * Microsoft's `/events/delta` resource ("SyncEvents") rejects
+ * `$filter`/`$orderby`/`$select`/`$expand`/`$search` outright — there is no
+ * way to bound a delta query by date. So any request with `min`/`max` set
+ * (the quick pass, or a manual start with an explicit window) uses a plain,
+ * non-delta `/events` listing instead; only a fully unfiltered request may
+ * use the real delta chain that yields a `deltaLink` for future incremental
+ * syncs.
  */
 export async function syncOutlookCalendar(
   api: GraphApi,
@@ -609,43 +643,37 @@ export async function syncOutlookCalendar(
   events: OutlookEvent[];
   state: SyncState;
 }> {
-  let url: string;
+  const resource =
+    calendarId === "primary"
+      ? "/me/events"
+      : `/me/calendars/${calendarId}/events`;
 
-  // If we have a delta link (full URL with token), use it directly
+  const bounded = !!(state.min || state.max);
+  const mode: "listing" | "delta" = bounded ? "listing" : "delta";
+
+  let url: string;
   if (state.state && state.state.startsWith("http")) {
+    // Continuing pagination via a full nextLink/deltaLink URL.
     url = state.state;
   } else if (state.state) {
-    // We have a delta token, append it to the URL
-    const resource =
-      calendarId === "primary"
-        ? "/me/events"
-        : `/me/calendars/${calendarId}/events`;
+    // Continuing a delta chain via a bare deltaToken.
     url = `https://graph.microsoft.com/v1.0${resource}/delta?$deltatoken=${state.state}`;
-  } else {
-    // Initial sync - use delta query without token
-    const resource =
-      calendarId === "primary"
-        ? "/me/events"
-        : `/me/calendars/${calendarId}/events`;
-
+  } else if (bounded) {
+    // Bounded request: plain (non-delta) filtered listing.
     const params: string[] = [];
-
-    // Add time filter if specified
     if (state.min && state.max) {
-      // Both min and max - use combined filter
       params.push(
         `$filter=start/dateTime ge '${state.min.toISOString()}' and start/dateTime lt '${state.max.toISOString()}'`
       );
     } else if (state.min) {
-      // Only min
       params.push(`$filter=start/dateTime ge '${state.min.toISOString()}'`);
     } else if (state.max) {
-      // Only max
       params.push(`$filter=start/dateTime lt '${state.max.toISOString()}'`);
     }
-
-    const queryString = params.length > 0 ? `?${params.join("&")}` : "";
-    url = `https://graph.microsoft.com/v1.0${resource}/delta${queryString}`;
+    url = `https://graph.microsoft.com/v1.0${resource}?${params.join("&")}`;
+  } else {
+    // Unbounded: real delta query, no query params allowed.
+    url = `https://graph.microsoft.com/v1.0${resource}/delta`;
   }
 
   const data = (await api.call("GET", url)) as {
@@ -655,7 +683,7 @@ export async function syncOutlookCalendar(
   } | null;
 
   if (!data) {
-    // Delta token expired or sync failed, need full sync
+    // Token expired (410) or resource missing (404) — restart from scratch.
     const newState: SyncState = {
       calendarId,
       min: state.min,
@@ -665,12 +693,14 @@ export async function syncOutlookCalendar(
     return syncOutlookCalendar(api, calendarId, newState);
   }
 
-  // Extract next link or delta link
+  // Extract next link (listing or mid-delta pagination) or delta link
+  // (delta chain complete for this page).
   const nextLink = data["@odata.nextLink"];
   const deltaLink = data["@odata.deltaLink"];
 
   const nextState: SyncState = {
     calendarId,
+    mode,
     state: nextLink || deltaLink,
     more: !!nextLink,
     min: state.min,

connectors/outlook/src/calendar/sync.ts

@@ -1120,10 +1120,13 @@ export async function initOutlookCalendarFn(
   }
 
   // Two-pass initial sync:
-  // - Quick pass (`phase: "quick"`) walks `timeMin = now` so upcoming
+  // - Quick pass (`phase: "quick"`) walks `timeMin = now` (a plain, non-delta
+  //   filtered /events listing — see syncOutlookCalendar) so upcoming
   //   meetings surface in the activity feed immediately.
-  // - Full pass (`phase: "full"`, queued at the terminal batch of the
-  //   quick pass) walks the 2-year historical backfill.
+  // - Full pass (`phase: "full"`, queued at the terminal batch of the quick
+  //   pass) walks the entire event history via an unfiltered /events/delta,
+  //   which is the only way to establish the deltaLink incremental syncs
+  //   reuse afterward.
   // Both passes share the sync lock acquired above. The quick→full
   // transition happens inside syncOutlookBatch without releasing.
   const initialState: SyncState = {
@@ -1314,20 +1317,20 @@ export async function syncOutlookBatchFn(
     }
 
     // Quick pass done: transition to full pass without releasing
-    // the lock. The full pass walks the historical range
-    // (timeMin = 2y ago) and picks up long-running recurring
-    // masters that timeMin = now excluded. Any exception
-    // instances the quick pass buffered into pending_occ: are
-    // carried across; they're only cleared when the full pass
+    // the lock. The full pass walks the entire event history and
+    // picks up long-running recurring masters that timeMin = now
+    // excluded. It's deliberately unbounded (no min/max): Microsoft
+    // Graph's /events/delta resource rejects $filter entirely, so a
+    // bounded historical window isn't possible on delta — this pass
+    // has to walk everything once to establish the deltaLink that
+    // startIncrementalSyncFn reuses for webhook-driven syncs going
+    // forward (see syncOutlookCalendar in graph-api.ts). Any
+    // exception instances the quick pass buffered into pending_occ:
+    // are carried across; they're only cleared when the full pass
     // completes below.
     if (syncState.phase === "quick") {
-      const historyMin = new Date();
-      historyMin.setFullYear(historyMin.getFullYear() - 2);
-      historyMin.setMonth(0, 1);
-      historyMin.setHours(0, 0, 0, 0);
       const fullState: SyncState = {
         calendarId,
-        min: historyMin,
         sequence: 1,
         phase: "full",
       };

connectors/outlook/src/compose.ts

@@ -34,17 +34,25 @@ export async function composeChannels(
 ): Promise<Channel[]> {
   const grantedScopes = new Set(token.scopes ?? []);
 
-  const result: Channel[] = [];
-
-  for (const product of products) {
-    const hasAllScopes = product.requiredScopes.every((s) => grantedScopes.has(s));
-    if (!hasAllScopes) continue;
+  // Enumerate every eligible product concurrently (each getRawChannels is an
+  // independent network call to Microsoft Graph). Order is preserved by
+  // enumerating results in `eligible` order, which is products' declaration
+  // order. See connectors/google/src/compose.ts for the reference pattern —
+  // this function used to await each product serially, which paid the sum of
+  // every product's round-trips (plus Mail's own internal serial calls)
+  // during the synchronous connect-time getChannels() call.
+  const eligible = products.filter((product) =>
+    product.requiredScopes.every((s) => grantedScopes.has(s))
+  );
+  const perProduct = await Promise.all(
+    eligible.map((product) => product.getRawChannels(token))
+  );
 
-    const rawChannels = await product.getRawChannels(token);
-    for (const raw of rawChannels) {
+  const result: Channel[] = [];
+  eligible.forEach((product, i) => {
+    for (const raw of perProduct[i]) {
       result.push(prefixChannel(product.key, raw, product.linkTypes));
     }
-  }
-
+  });
   return result;
 }

connectors/outlook/src/mail/bundle.test.ts

@@ -81,7 +81,6 @@ describe("processConversationsFn — calendar-thread bundling", () => {
       messages: [
         baseMessage({
           meetingMessageType: "meetingRequest",
-          meetingRequestType: "fullUpdate",
           event: { iCalUId: "uid-1" },
         }),
       ],

connectors/outlook/src/mail/channels.ts

@@ -8,8 +8,8 @@ import { EXCLUDED_WELL_KNOWN, GraphMailApi } from "./graph-mail-api";
 // ---------------------------------------------------------------------------
 
 export const OUTLOOK_MAIL_SCOPES: string[] = [
-  "https://graph.microsoft.com/mail.readwrite",
-  "https://graph.microsoft.com/mail.send",
+  "https://graph.microsoft.com/Mail.ReadWrite",
+  "https://graph.microsoft.com/Mail.Send",
 ];
 
 // ---------------------------------------------------------------------------
@@ -63,8 +63,12 @@ export async function getOutlookMailChannels(
   token: AuthToken
 ): Promise<Channel[]> {
   const api = new GraphMailApi(token.token);
-  const folders = await api.getMailFolders();
-  const wellKnown = await api.getWellKnownFolderIds();
+  // Independent Graph calls — run concurrently rather than paying the sum of
+  // both round-trips during the synchronous connect-time getChannels() call.
+  const [folders, wellKnown] = await Promise.all([
+    api.getMailFolders(),
+    api.getWellKnownFolderIds(),
+  ]);
 
   const excluded = new Set(
     EXCLUDED_WELL_KNOWN.map((n) => wellKnown[n]).filter(Boolean) as string[]

connectors/outlook/src/mail/enrich.test.ts

@@ -123,7 +123,7 @@ describe("enrichLinkContactsFromOutlook", () => {
       enrichLinkContactsFromOutlook(
         [link],
         "tok",
-        ["https://graph.microsoft.com/mail.readwrite"]
+        ["https://graph.microsoft.com/Mail.ReadWrite"]
       )
     ).resolves.toBeUndefined();
 

connectors/outlook/src/mail/enrich.ts

@@ -16,8 +16,8 @@ import type {
 } from "@plotday/twister/plot";
 
 const GRAPH = "https://graph.microsoft.com/v1.0";
-const SCOPE_PEOPLE = "https://graph.microsoft.com/people.read";
-const SCOPE_CONTACTS = "https://graph.microsoft.com/contacts.read";
+const SCOPE_PEOPLE = "https://graph.microsoft.com/People.Read";
+const SCOPE_CONTACTS = "https://graph.microsoft.com/Contacts.Read";
 
 /** Scopes the enrichment helpers depend on. Merge into the connector's
  * `scopes` (via `Integrations.MergeScopes`) to enable enrichment. */