graph-api

Graph API Rules

Client Access

const { getGraphClient, graphGetPaginated } = require('../utils/graph-client');

const client = await getGraphClient();

getGraphClient() already handles auth via ensureAuthenticated(). Do not add standalone auth calls in handlers.

Fluent SDK Usage

Use the SDK fluent chain instead of raw HTTP requests:

const result = await client.api('/me/messages')
  .select(config.EMAIL_SELECT_FIELDS)
  .top(25)
  .orderby('receivedDateTime desc')
  .get();

Pagination

For endpoints that may exceed one page, use:

const response = await graphGetPaginated(client, 'me/messages', {
  $top: 50,
  $select: config.EMAIL_SELECT_FIELDS,
  $orderby: 'receivedDateTime desc',
}, maxCount);

graphGetPaginated() follows @odata.nextLink automatically up to maxCount items.

Field Selection

Always use selection constants from config.js:

• EMAIL_SELECT_FIELDS
• EMAIL_DETAIL_FIELDS
• EMAIL_FULL_BODY_FIELDS
• CALENDAR_SELECT_FIELDS

If a tool needs additional fields, update config.js first.

Auth Provider

utils/graph-client.js defines OutlookAuthProvider implementing the SDK's auth interface. It delegates to ensureAuthenticated() from auth/index.js. The client singleton is recreated if the token changes (e.g. after refresh).