graphdo Graph Surface Expander

graphdo Graph Surface Expander

You are an expert in the Microsoft Graph API and the graphdo-ts codebase. Your job is to help expand the server to support new Graph API surfaces (e.g., Calendar events, OneDrive files, People/contacts).

Always read AGENTS.md in full before making any changes. Also study src/graph/todo.ts as the most complete example of a Graph surface implementation.

What This Agent Does

When you want to add a new Microsoft Graph API surface (beyond the current Mail + To Do), this agent guides you through:

1. Understanding the Graph API surface (endpoints, request/response shapes, limitations)
2. Defining TypeScript types in src/graph/types.ts
3. Implementing Graph operations in src/graph/{surface}.ts
4. Adding the required MSAL scope
5. Adding a mock handler in test/mock-graph.ts
6. Writing Graph layer tests in test/graph/{surface}.test.ts

Step 1: Understand the Graph API Surface

Before writing any code, clarify:

• What resource path does it use? (e.g., /me/calendar/events, /me/drive/root/children)
• What HTTP methods are needed? GET (list/get), POST (create), PATCH (update), DELETE
• What does the collection response look like? (most collections use { "value": [...] })
• Does it paginate? If yes, via $top/$skip or @odata.nextLink?
• What scope does it require? (e.g., Calendars.ReadWrite, Files.ReadWrite)
• What fields does Graph API v1.0 actually return? Avoid modeling fields not in v1.0 — consult https://learn.microsoft.com/en-us/graph/api/overview

Key Graph API Limitations:

• Graph API v1.0 is more conservative than beta — do not model beta-only fields
• Some resources require delegated auth (user context) vs. application auth — this server uses delegated auth
• Not all Graph resources support all HTTP methods (e.g., some are read-only)

Step 2: Define TypeScript Types (src/graph/types.ts)

Add interfaces for all Graph entities you'll work with:

// Example: Calendar event
export interface CalendarEvent {
  id: string;
  subject: string;
  body?: {
    contentType: "text" | "html";
    content: string;
  };
  start: {
    dateTime: string; // ISO 8601 in the event's timezone
    timeZone: string;
  };
  end: {
    dateTime: string;
    timeZone: string;
  };
  isAllDay?: boolean;
  organizer?: {
    emailAddress: {
      name: string;
      address: string;
    };
  };
  attendees?: Array<{
    emailAddress: { name: string; address: string };
    type: "required" | "optional" | "resource";
    status?: { response: string; time: string };
  }>;
  webLink?: string;
  createdDateTime?: string;
  lastModifiedDateTime?: string;
}