@littlebearapps/outlook-assistant 3.5.0 → 3.5.1

package/.env.example

@@ -23,3 +23,8 @@ USE_TEST_MODE=false
 
 # Optional: Enable immutable IDs (IDs persist through folder moves)
 # OUTLOOK_IMMUTABLE_IDS=true
+
+# Optional: Default authentication method (device-code or browser)
+# device-code: No auth server needed, works remotely/headless
+# browser: Traditional OAuth redirect via localhost:3333
+# OUTLOOK_AUTH_METHOD=device-code

package/README.md

@@ -152,6 +152,7 @@ You need a Microsoft Azure app registration to authenticate. See the **[Azure Se
 2. Set redirect URI to `http://localhost:3333/auth/callback`
 3. Add Microsoft Graph delegated permissions (Mail, Calendar, Contacts)
 4. Create a client secret and copy the **Value** (not the Secret ID)
+5. Enable **"Allow public client flows"** in Authentication > Advanced settings (for device code flow)
 
 ### 3. Configure Your MCP Client
 
@@ -340,7 +341,21 @@ If installed from source, use `node` instead of `npx`:
 
 ## Authentication Flow
 
-### Step 1: Start the Auth Server
+### Device Code Flow (Default — Recommended)
+
+No auth server needed. Works everywhere, including remote/headless environments.
+
+1. Ask your AI assistant to authenticate (calls `auth` tool with `action=authenticate`)
+2. Visit the URL shown (`microsoft.com/devicelogin`) on **any** browser, **any** device
+3. Enter the code, sign in with your Microsoft account, and grant permissions
+4. Tell your AI assistant to complete authentication (calls `auth` with `action=device-code-complete`)
+5. Tokens are saved to `~/.outlook-assistant-tokens.json` and **refresh automatically**
+
+> **Prerequisite**: Enable "Allow public client flows" in Azure Portal > your app > Authentication > Advanced settings.
+
+### Browser Redirect Flow (Alternative)
+
+For localhost development or if you prefer the traditional OAuth flow:
 
 ```bash
 npm run auth-server
@@ -348,14 +363,11 @@ npm run auth-server
 
 This starts a local server on port 3333 to handle the OAuth callback.
 
-> **Note**: The auth server reads `OUTLOOK_CLIENT_ID` and `OUTLOOK_CLIENT_SECRET` from environment variables (or `MS_CLIENT_ID`/`MS_CLIENT_SECRET`). When running the auth server separately, ensure your `.env` file is in the project root or export the variables in your shell. Your MCP client's `"env"` config only applies to the MCP server process, not a separately-started auth server.
-
-### Step 2: Authenticate
-
-1. In your AI assistant, use the `auth` tool with `action=authenticate`
+1. In your AI assistant, use the `auth` tool with `action=authenticate, method=browser`
 2. Open the provided URL in your browser
-3. Sign in with your Microsoft account and grant permissions
-4. Tokens are saved to `~/.outlook-assistant-tokens.json` and refresh automatically
+3. Sign in and grant permissions — tokens are saved automatically
+
+> **Note**: The auth server reads `OUTLOOK_CLIENT_ID` and `OUTLOOK_CLIENT_SECRET` from environment variables. Your MCP client's `"env"` config only applies to the MCP server process, not a separately-started auth server.
 
 ## Directory Structure
 
@@ -409,7 +421,11 @@ You're using the Secret **ID** instead of the Secret **Value**. Go to Azure Port
 
 ### Authentication URL doesn't work
 
-Start the auth server first: `npm run auth-server`
+If using browser flow: start the auth server first with `npm run auth-server`. If using device code flow: visit `microsoft.com/devicelogin` instead.
+
+### Device code "invalid_client"
+
+Enable "Allow public client flows" in Azure Portal > App registrations > Authentication > Advanced settings.
 
 ### Empty API responses
 

package/auth/device-code.js

@@ -0,0 +1,139 @@
+/**
+ * Device Code Flow for Microsoft OAuth2
+ *
+ * Enables authentication without browser redirect — ideal for
+ * headless/remote environments (SSH, VPS, containers).
+ *
+ * The user gets a short code, visits https://microsoft.com/devicelogin
+ * on any device, and enters it. No auth server or port forwarding needed.
+ */
+const https = require('https');
+const querystring = require('querystring');
+const config = require('../config');
+
+/**
+ * POST helper for OAuth2 endpoints
+ * @param {string} url - Full URL to POST to
+ * @param {string} postData - URL-encoded form data
+ * @returns {Promise<{statusCode: number, body: object}>}
+ */
+function postRequest(url, postData) {
+  return new Promise((resolve, reject) => {
+    const req = https.request(
+      url,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded',
+          'Content-Length': Buffer.byteLength(postData),
+        },
+      },
+      (res) => {
+        let data = '';
+        res.on('data', (chunk) => (data += chunk));
+        res.on('end', () => {
+          try {
+            resolve({ statusCode: res.statusCode, body: JSON.parse(data) });
+          } catch (_e) {
+            reject(new Error(`Failed to parse response: ${data}`));
+          }
+        });
+      }
+    );
+    req.on('error', reject);
+    req.write(postData);
+    req.end();
+  });
+}
+
+/**
+ * Initiates the device code flow by requesting a device code from Azure.
+ * @param {string} clientId - Azure app client ID
+ * @param {string[]} scopes - OAuth2 scopes to request
+ * @returns {Promise<{userCode: string, verificationUri: string, deviceCode: string, expiresIn: number, interval: number, message: string}>}
+ */
+async function initiateDeviceCodeFlow(clientId, scopes) {
+  const postData = querystring.stringify({
+    client_id: clientId,
+    scope: scopes.join(' '),
+  });
+
+  const endpoint = config.AUTH_CONFIG.deviceCodeEndpoint;
+  const { statusCode, body } = await postRequest(endpoint, postData);
+
+  if (statusCode < 200 || statusCode >= 300) {
+    throw new Error(
+      body.error_description ||
+        `Device code request failed with status ${statusCode}`
+    );
+  }
+
+  return {
+    userCode: body.user_code,
+    verificationUri: body.verification_uri,
+    deviceCode: body.device_code,
+    expiresIn: body.expires_in,
+    interval: body.interval || 5,
+    message: body.message,
+  };
+}
+
+/**
+ * Polls the token endpoint until the user completes authentication.
+ * @param {string} clientId - Azure app client ID
+ * @param {string} deviceCode - Device code from initiateDeviceCodeFlow
+ * @param {number} interval - Polling interval in seconds
+ * @param {number} expiresIn - Seconds until the device code expires
+ * @returns {Promise<{access_token: string, refresh_token: string, expires_in: number, scope: string, token_type: string}>}
+ */
+async function pollForToken(clientId, deviceCode, interval, expiresIn) {
+  const endpoint = config.AUTH_CONFIG.tokenEndpoint;
+  const deadline = Date.now() + expiresIn * 1000;
+  let pollInterval = interval;
+
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, pollInterval * 1000));
+
+    const postData = querystring.stringify({
+      client_id: clientId,
+      grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+      device_code: deviceCode,
+    });
+
+    const { statusCode, body } = await postRequest(endpoint, postData);
+
+    if (statusCode >= 200 && statusCode < 300) {
+      return body;
+    }
+
+    switch (body.error) {
+      case 'authorization_pending':
+        // User hasn't completed auth yet — keep polling
+        break;
+      case 'slow_down':
+        // Server asked us to slow down — increase interval by 5s
+        pollInterval += 5;
+        break;
+      case 'authorization_declined':
+        throw new Error('Authentication was declined by the user.');
+      case 'expired_token':
+        throw new Error(
+          'Device code expired. Please restart the authentication process.'
+        );
+      default:
+        throw new Error(
+          body.error_description ||
+            `Token polling failed: ${body.error || `status ${statusCode}`}`
+        );
+    }
+  }
+
+  throw new Error(
+    'Device code expired. Please restart the authentication process.'
+  );
+}
+
+module.exports = {
+  initiateDeviceCodeFlow,
+  pollForToken,
+};

package/auth/index.js

@@ -2,22 +2,32 @@
  * Authentication module for Outlook Assistant server
  */
 const tokenManager = require('./token-manager');
+const TokenStorage = require('./token-storage');
+const config = require('../config');
 const { authTools } = require('./tools');
 
+// Singleton TokenStorage instance with auto-refresh support
+const tokenStorage = new TokenStorage({
+  clientId: config.AUTH_CONFIG.clientId,
+  clientSecret: config.AUTH_CONFIG.clientSecret,
+  tokenStorePath: config.AUTH_CONFIG.tokenStorePath,
+  scopes: config.AUTH_CONFIG.scopes,
+  tokenEndpoint: config.AUTH_CONFIG.tokenEndpoint,
+});
+
 /**
- * Ensures the user is authenticated and returns an access token
+ * Ensures the user is authenticated and returns an access token.
+ * Automatically refreshes expired tokens via tokenStorage.
  * @param {boolean} forceNew - Whether to force a new authentication
  * @returns {Promise<string>} - Access token
  * @throws {Error} - If authentication fails
  */
 async function ensureAuthenticated(forceNew = false) {
   if (forceNew) {
-    // Force re-authentication
     throw new Error('Authentication required');
   }
 
-  // Check for existing token
-  const accessToken = tokenManager.getAccessToken();
+  const accessToken = await tokenStorage.getValidAccessToken();
   if (!accessToken) {
     throw new Error('Authentication required');
   }
@@ -26,7 +36,8 @@ async function ensureAuthenticated(forceNew = false) {
 }
 
 module.exports = {
-  tokenManager,
+  tokenManager, // deprecated: use tokenStorage
+  tokenStorage,
   authTools,
   ensureAuthenticated,
 };

package/auth/tools.js

@@ -3,6 +3,7 @@
  */
 const config = require('../config');
 const tokenManager = require('./token-manager');
+const { initiateDeviceCodeFlow, pollForToken } = require('./device-code');
 
 /**
  * About tool handler
@@ -46,18 +47,14 @@ async function handleAbout() {
 }
 
 /**
- * Authentication tool handler
+ * Authentication tool handler — supports browser redirect and device code flow.
  * @param {object} args - Tool arguments
  * @returns {object} - MCP response
  */
 async function handleAuthenticate(args) {
-  const _force = args && args.force === true;
-
   // For test mode, create a test token
   if (config.USE_TEST_MODE) {
-    // Create a test token with a 1-hour expiry
     tokenManager.createTestTokens();
-
     return {
       content: [
         {
@@ -68,43 +65,205 @@ async function handleAuthenticate(args) {
     };
   }
 
-  // For real authentication, generate an auth URL and instruct the user to visit it
+  const method = args?.method || config.AUTH_CONFIG.defaultAuthMethod;
+
+  if (method === 'device-code') {
+    return handleDeviceCodeAuth();
+  }
+
+  // Browser redirect flow (existing behaviour)
   const authUrl = `${config.AUTH_CONFIG.authServerUrl}/auth?client_id=${config.AUTH_CONFIG.clientId}`;
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `Authentication required. Please visit the following URL to authenticate with Microsoft: ${authUrl}\n\nAfter authentication, you will be redirected back to this application.\n\nNote: The auth server must be running on port 3333. If working remotely, consider using method=device-code instead.`,
+      },
+    ],
+  };
+}
+
+// Module-level state for pending device code flow
+let pendingDeviceCode = null;
+
+/**
+ * Device code flow step 1 — request a code for the user to enter.
+ * Returns the code + URL immediately. Call device-code-complete to finish.
+ * @returns {object} - MCP response
+ */
+async function handleDeviceCodeAuth() {
+  const clientId = config.AUTH_CONFIG.clientId;
+  if (!clientId) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'Error: OUTLOOK_CLIENT_ID is not configured.',
+        },
+      ],
+    };
+  }
+
+  console.error('[AUTH] Starting device code flow...');
+  const response = await initiateDeviceCodeFlow(
+    clientId,
+    config.AUTH_CONFIG.scopes
+  );
+
+  // Store for the completion step
+  pendingDeviceCode = {
+    deviceCode: response.deviceCode,
+    interval: response.interval,
+    expiresIn: response.expiresIn,
+    expiresAt: Date.now() + response.expiresIn * 1000,
+  };
+
+  console.error(
+    `[AUTH] Device code: ${response.userCode}, expires in ${response.expiresIn}s`
+  );
 
   return {
     content: [
       {
         type: 'text',
-        text: `Authentication required. Please visit the following URL to authenticate with Microsoft: ${authUrl}\n\nAfter authentication, you will be redirected back to this application.`,
+        text: [
+          `## Device Code Authentication\n`,
+          `Visit: **${response.verificationUri}**`,
+          `Enter code: **${response.userCode}**\n`,
+          `The code expires in ${Math.floor(response.expiresIn / 60)} minutes.\n`,
+          `After entering the code and signing in, call this tool again with \`action=device-code-complete\` to finish authentication.`,
+        ].join('\n'),
       },
     ],
   };
 }
 
 /**
- * Check authentication status tool handler
+ * Device code flow step 2 — poll until the user completes authentication.
+ * @returns {object} - MCP response
+ */
+async function handleDeviceCodeComplete() {
+  if (!pendingDeviceCode) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'No pending device code flow. Call authenticate with method=device-code first.',
+        },
+      ],
+    };
+  }
+
+  if (Date.now() > pendingDeviceCode.expiresAt) {
+    pendingDeviceCode = null;
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'Device code has expired. Please start a new authentication with action=authenticate.',
+        },
+      ],
+    };
+  }
+
+  const clientId = config.AUTH_CONFIG.clientId;
+
+  try {
+    console.error('[AUTH] Polling for device code completion...');
+    const tokenResponse = await pollForToken(
+      clientId,
+      pendingDeviceCode.deviceCode,
+      pendingDeviceCode.interval,
+      Math.ceil((pendingDeviceCode.expiresAt - Date.now()) / 1000)
+    );
+
+    pendingDeviceCode = null;
+
+    // Save tokens using TokenStorage
+    const TokenStorage = require('./token-storage');
+    const tokenStorage = new TokenStorage({
+      clientId: config.AUTH_CONFIG.clientId,
+      clientSecret: config.AUTH_CONFIG.clientSecret,
+      tokenStorePath: config.AUTH_CONFIG.tokenStorePath,
+      scopes: config.AUTH_CONFIG.scopes,
+      tokenEndpoint: config.AUTH_CONFIG.tokenEndpoint,
+    });
+
+    tokenStorage.tokens = {
+      access_token: tokenResponse.access_token,
+      refresh_token: tokenResponse.refresh_token,
+      expires_in: tokenResponse.expires_in,
+      expires_at: Date.now() + tokenResponse.expires_in * 1000,
+      scope: tokenResponse.scope,
+      token_type: tokenResponse.token_type,
+    };
+    await tokenStorage._saveTokensToFile();
+
+    console.error('[AUTH] Device code flow completed successfully.');
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'Authentication successful! Tokens saved. You can now use Outlook tools.',
+        },
+      ],
+    };
+  } catch (error) {
+    pendingDeviceCode = null;
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Authentication failed: ${error.message}`,
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * Check authentication status — attempts token refresh if expired.
  * @returns {object} - MCP response
  */
 async function handleCheckAuthStatus() {
   console.error('[CHECK-AUTH-STATUS] Starting authentication status check');
 
-  const tokens = tokenManager.loadTokenCache();
+  // Use TokenStorage for accurate status (includes refresh attempt)
+  const TokenStorage = require('./token-storage');
+  const tokenStorage = new TokenStorage({
+    clientId: config.AUTH_CONFIG.clientId,
+    clientSecret: config.AUTH_CONFIG.clientSecret,
+    tokenStorePath: config.AUTH_CONFIG.tokenStorePath,
+    scopes: config.AUTH_CONFIG.scopes,
+    tokenEndpoint: config.AUTH_CONFIG.tokenEndpoint,
+  });
 
-  console.error(`[CHECK-AUTH-STATUS] Tokens loaded: ${tokens ? 'YES' : 'NO'}`);
+  const accessToken = await tokenStorage.getValidAccessToken();
 
-  if (!tokens || !tokens.access_token) {
-    console.error('[CHECK-AUTH-STATUS] No valid access token found');
+  if (!accessToken) {
+    console.error('[CHECK-AUTH-STATUS] No valid access token');
     return {
       content: [{ type: 'text', text: 'Not authenticated' }],
     };
   }
 
-  console.error('[CHECK-AUTH-STATUS] Access token present');
-  console.error(`[CHECK-AUTH-STATUS] Token expires at: ${tokens.expires_at}`);
-  console.error(`[CHECK-AUTH-STATUS] Current time: ${Date.now()}`);
+  const expiresAt = tokenStorage.getExpiryTime();
+  const expiresIn = expiresAt
+    ? Math.round((expiresAt - Date.now()) / 60000)
+    : 'unknown';
+
+  console.error(
+    `[CHECK-AUTH-STATUS] Authenticated, token expires in ~${expiresIn} min`
+  );
 
   return {
-    content: [{ type: 'text', text: 'Authenticated and ready' }],
+    content: [
+      {
+        type: 'text',
+        text: `Authenticated and ready (token expires in ~${expiresIn} minutes)`,
+      },
+    ],
   };
 }
 
@@ -113,7 +272,7 @@ const authTools = [
   {
     name: 'auth',
     description:
-      'Manage authentication with Microsoft Graph API. action=status (default) checks auth state, action=authenticate starts OAuth flow, action=about shows server info.',
+      'Manage authentication with Microsoft Graph API. action=status (default) checks auth state and refreshes tokens if needed, action=authenticate starts OAuth flow (device-code by default — no auth server needed), action=device-code-complete finishes device code auth after user enters code, action=about shows server info.',
     annotations: {
       title: 'Authentication',
       readOnlyHint: false,
@@ -125,9 +284,15 @@ const authTools = [
       properties: {
         action: {
           type: 'string',
-          enum: ['status', 'authenticate', 'about'],
+          enum: ['status', 'authenticate', 'device-code-complete', 'about'],
           description: 'Action to perform (default: status)',
         },
+        method: {
+          type: 'string',
+          enum: ['device-code', 'browser'],
+          description:
+            'Auth method for action=authenticate. device-code (default): no auth server needed, works remotely. browser: traditional OAuth redirect via port 3333.',
+        },
         force: {
           type: 'boolean',
           description:
@@ -141,6 +306,8 @@ const authTools = [
       switch (action) {
         case 'authenticate':
           return handleAuthenticate(args);
+        case 'device-code-complete':
+          return handleDeviceCodeComplete();
         case 'about':
           return handleAbout();
         case 'status':
@@ -155,5 +322,7 @@ module.exports = {
   authTools,
   handleAbout,
   handleAuthenticate,
+  handleDeviceCodeAuth,
+  handleDeviceCodeComplete,
   handleCheckAuthStatus,
 };

package/config.js

@@ -54,6 +54,10 @@ module.exports = {
     ],
     tokenStorePath: path.join(homeDir, '.outlook-assistant-tokens.json'),
     authServerUrl: 'http://localhost:3333',
+    deviceCodeEndpoint:
+      'https://login.microsoftonline.com/common/oauth2/v2.0/devicecode',
+    tokenEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+    defaultAuthMethod: process.env.OUTLOOK_AUTH_METHOD || 'device-code',
   },
 
   // Microsoft Graph API

package/llms-install.md

@@ -0,0 +1,90 @@
+# Installing Outlook Assistant
+
+## Quick Install (npx — no global install needed)
+
+Add to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "outlook": {
+      "command": "npx",
+      "args": ["-y", "@littlebearapps/outlook-assistant"],
+      "env": {
+        "OUTLOOK_CLIENT_ID": "<user-must-provide>",
+        "OUTLOOK_CLIENT_SECRET": "<user-must-provide>"
+      }
+    }
+  }
+}
+```
+
+## Prerequisites
+
+1. **Node.js 18+** must be installed
+2. **Azure app registration** is required for authentication (free tier works)
+
+## Getting the Client ID and Secret
+
+Users must create an Azure app registration to get credentials:
+
+1. Go to https://portal.azure.com/ and sign in
+2. Search for "App registrations" → click "New registration"
+3. Name: "Outlook Assistant" (or any name)
+4. Supported account types: "Accounts in any organizational directory and personal Microsoft accounts"
+5. Redirect URI: platform "Web", URI `http://localhost:3333/auth/callback`
+6. Click "Register"
+7. Copy the **Application (client) ID** → this is `OUTLOOK_CLIENT_ID`
+
+### Create a client secret:
+1. Go to "Certificates & secrets" → "New client secret"
+2. Add a description, select expiration, click "Add"
+3. **Copy the Value immediately** (not the Secret ID) → this is `OUTLOOK_CLIENT_SECRET`
+
+### Add API permissions:
+1. Go to "API permissions" → "Add a permission" → "Microsoft Graph" → "Delegated permissions"
+2. Add: `offline_access`, `User.Read`, `Mail.Read`, `Mail.ReadWrite`, `Mail.Send`, `Calendars.Read`, `Calendars.ReadWrite`, `Contacts.Read`, `Contacts.ReadWrite`, `People.Read`, `MailboxSettings.ReadWrite`
+3. Click "Add permissions"
+
+## First-Time Authentication
+
+After configuring the MCP server:
+
+1. Start the auth server: `npx @littlebearapps/outlook-assistant-auth` (or run `npm run auth-server` from source)
+2. Use the `auth` tool with `action=authenticate` to get an OAuth URL
+3. Open the URL in a browser, sign in with your Microsoft account
+4. Grant permissions — tokens are saved to `~/.outlook-assistant-tokens.json` and refresh automatically
+
+**Note**: The auth server needs `OUTLOOK_CLIENT_ID` and `OUTLOOK_CLIENT_SECRET` as environment variables. If running it separately from the MCP server, export them in your shell or create a `.env` file.
+
+## Configuration Files by Client
+
+### Claude Desktop
+File: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
+
+### Claude Code
+```bash
+claude mcp add outlook -- npx @littlebearapps/outlook-assistant
+```
+
+### Cursor
+File: `.cursor/mcp.json` in your project root
+
+### Windsurf
+File: `~/.codeium/windsurf/mcp_config.json`
+
+## Verify Installation
+
+After authentication, test with:
+- `auth` tool with `action=status` — should show "authenticated"
+- `search-emails` with no parameters — should list recent inbox emails
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| "Invalid client secret" (AADSTS7000215) | Use the secret **Value**, not the Secret ID |
+| Auth URL doesn't work | Start the auth server first |
+| "EADDRINUSE :3333" | Run `npx kill-port 3333` then restart auth server |
+| Empty API responses | Run `auth` tool with `action=status` to check token |
+| Search returns no results (personal account) | Use `from`, `subject`, `to` filters instead of `query` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/outlook-assistant",
-  "version": "3.5.0",
+  "version": "3.5.1",
   "mcpName": "io.github.littlebearapps/outlook-assistant",
   "description": "Outlook Assistant — MCP server with 21 tools for email, calendar, contacts, and settings via Microsoft Graph API",
   "main": "index.js",
@@ -70,7 +70,8 @@
     ".env.example",
     "README.md",
     "LICENSE",
-    "llms.txt"
+    "llms.txt",
+    "llms-install.md"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",

package/utils/graph-api.js

@@ -325,9 +325,67 @@ async function callGraphAPIRaw(accessToken, emailId) {
   });
 }
 
+/**
+ * Calls Graph API with automatic auth and 401 retry.
+ * Gets token via ensureAuthenticated(), and if a 401 occurs,
+ * refreshes the token and retries once.
+ * @param {string} method - HTTP method
+ * @param {string} path - API endpoint path
+ * @param {object} data - Request body
+ * @param {object} queryParams - Query parameters
+ * @param {object} extraHeaders - Additional headers
+ * @returns {Promise<object>} - API response
+ */
+async function callGraphAPIWithAuth(
+  method,
+  path,
+  data = null,
+  queryParams = {},
+  extraHeaders = {}
+) {
+  // Lazy require to avoid circular dependency
+  const { ensureAuthenticated, tokenStorage } = require('../auth');
+
+  const accessToken = await ensureAuthenticated();
+  try {
+    return await callGraphAPI(
+      accessToken,
+      method,
+      path,
+      data,
+      queryParams,
+      extraHeaders
+    );
+  } catch (error) {
+    if (error.message === 'UNAUTHORIZED' && tokenStorage) {
+      console.error('[GRAPH-API] 401 received, attempting token refresh...');
+      try {
+        const newToken = await tokenStorage.refreshAccessToken();
+        if (newToken) {
+          return await callGraphAPI(
+            newToken,
+            method,
+            path,
+            data,
+            queryParams,
+            extraHeaders
+          );
+        }
+      } catch (refreshError) {
+        console.error(
+          '[GRAPH-API] Token refresh failed:',
+          refreshError.message
+        );
+      }
+    }
+    throw error;
+  }
+}
+
 module.exports = {
   callGraphAPI,
   callGraphAPIPaginated,
   callGraphAPIBatch,
   callGraphAPIRaw,
+  callGraphAPIWithAuth,
 };