Azure Microsoft Graph Utility

A TypeScript utility for Microsoft Graph API operations with automatic token management and cross-platform storage support.

✨ Features

✅ Global instance pattern - Configure once, export, use everywhere in your app
✅ AWS SDK-style API - Familiar Azure.service pattern (e.g., Azure.outlook.sendMail())
✅ Automatic token refresh - Handles token expiration transparently
✅ Multiple auth modes - Access token, refresh token, or custom token provider
✅ Cross-platform storage - Works on Windows, Mac, and Linux using XDG standards
✅ TypeScript support - Full type safety and autocomplete
✅ Fluent builders - Clean, chainable APIs for emails and Teams cards
✅ Zero config imports - Import configured instance, no setup needed at call site

Major Achievement: Three-Tier User System

Successfully designed and implemented a progressive complexity model for Azure authentication that supports all user types from beginners to enterprise.

Tier 1: Light User (Access Token Only)

Purpose: Quick testing, POC, experimentation

API:

Azure.config({ accessToken: "eyJ0eX..." });
await Azure.outlook.getMe();

Key Features:

Zero setup - paste token and go
No credentials required
Perfect for testing
Expires in ~1 hour
No automatic renewal

Critical Design Decision:

✅ Don't assume expiredAt - only set when Azure provides it
✅ Fail gracefully with helpful error message
✅ Don't force users to "upgrade" - respect their choice

Tier 2: Medium User (Refresh Token)

Purpose: Production automation, scheduled tasks, single-tenant apps

API:

Azure.config({
  refreshToken: "xxx",
  clientId: "...",
  clientSecret: "...",
  tenantId: "...",
});
await Azure.outlook.sendMail({...});

Key Features:

Automatic token refresh for ~90 days
Cross-platform storage (XDG standard)
Works for 90% of users

Storage Strategy:

✅ Store: refreshToken, accessToken, clientId, tenantId, expiresAt
❌ NEVER store: clientSecret (security best practice)
Client secret must be provided via init config

Tier 3: Super User (Token Provider)

Purpose: Enterprise apps, multi-tenant SaaS, long-running services

API:

Azure.config({
  clientId: "...",
  clientSecret: "...",
  tenantId: "...",
  tokenProvider: async (callback) => await getAuthCode(callback),
});
await Azure.teams.postMessage({...});

Key Features:

Never expires (provider handles rotation)
Multi-tenant support
Integration with secret vaults (HashiCorp Vault, AWS Secrets Manager, etc.)
Provider called only when needed
Skips storage (provider is source of truth)

🚀 Quick Start

Installation

npm install ms-graph-devtools

Best Practice: Global Instance Pattern (Recommended)

Create a single config file and export the configured instance:

// config/azure.ts (or src/lib/azure.ts, etc.)
import Azure from 'ms-graph-devtools';

Azure.config({
  clientId: process.env.AZURE_CLIENT_ID,
  clientSecret: process.env.AZURE_CLIENT_SECRET,
  tenantId: process.env.AZURE_TENANT_ID,
  tokenProvider: async (callback) => {
    return await Playwright.getAzureCode(callback);
  },
});

// Export configured instance - this is your single source of truth
export default Azure;

Then import and use everywhere in your app:

// anywhere in your codebase
import Azure from './config/azure';

// Use services directly - already configured!
await Azure.outlook.sendMail({...});
await Azure.teams.postMessage({...});
await Azure.calendar.getCalendars();
await Azure.sharePoint.getLists();

Why this pattern?

✅ Configure once, use everywhere
✅ Single source of truth for credentials
✅ No config duplication across files
✅ Easy to test (mock one import)
✅ Consistent auth across your entire app
✅ Clean imports - no config needed at call site

📖 API Reference

`Azure.config(config): void`

Set global configuration for all Azure services. Call once at app startup.

Parameters:

interface AzureConfig {
  // Authentication options (choose one):
  accessToken?: string;              // Light mode: temporary token (~1 hour)
  refreshToken?: string;             // Medium mode: 90-day auto-renewal
  tokenProvider?: (callback: string) => Promise<string> | string; // Super mode: infinite renewal

  // Required credentials:
  clientId?: string;                 // Azure app client ID
  clientSecret?: string;             // Azure app client secret
  tenantId?: string;                 // Azure tenant ID

  // Optional:
  scopes?: string[];                 // Custom OAuth scopes
  allowInsecure?: boolean;           // Allow insecure SSL (dev only)
}

Examples:

// Medium User: Refresh token (90-day renewal)
Azure.config({
  clientId: process.env.AZURE_CLIENT_ID,
  clientSecret: process.env.AZURE_CLIENT_SECRET,
  tenantId: process.env.AZURE_TENANT_ID,
  refreshToken: process.env.AZURE_REFRESH_TOKEN,
});

// Super User: Token provider (infinite renewal)
Azure.config({
  clientId: process.env.AZURE_CLIENT_ID,
  clientSecret: process.env.AZURE_CLIENT_SECRET,
  tenantId: process.env.AZURE_TENANT_ID,
  tokenProvider: async (callback) => {
    // Your custom auth logic (e.g., Playwright, browser automation)
    return await getAuthorizationCode(callback);
  },
});

// Light User: Access token only (temporary)
Azure.config({
  accessToken: "eyJ0eX...", // Expires in ~1 hour
});

Service Getters

After calling Azure.config(), access services directly:

Azure.outlook - Email operations
Azure.teams - Teams messaging and adaptive cards
Azure.calendar - Calendar and holidays
Azure.sharePoint - SharePoint lists and sites

`Azure.reset(): void`

Reset global configuration and clear all service instances. Useful for testing or switching accounts.

Azure.reset();
Azure.config({ refreshToken: "new-token" });

`Azure.listStoredCredentials(): Promise<Array>`

List all stored credential files. Useful for debugging multi-tenant setups.

const stored = await Azure.listStoredCredentials();
console.log(stored);
// [
//   { tenantId: 'abc123', clientId: 'def456', file: 'tokens.abc123.def456.json' },
//   { tenantId: 'xyz789', clientId: 'app2', file: 'tokens.xyz789.app2.json' },
//   { file: 'tokens.json' } // Legacy file
// ]

`Azure.clearStoredCredentials(tenantId?, clientId?): Promise<void>`

Clear stored credentials for a specific tenant/client or all.

// Clear specific tenant/client
await Azure.clearStoredCredentials("abc123", "def456");

// Clear all stored credentials
await Azure.clearStoredCredentials();

🔑 Token Management

Token Priority

The utility loads tokens in this priority order:

Memory - Token provided in init() config
Storage - Saved token file (cross-platform)
Provider - Custom tokenProvider callback
Error - If none available, throws helpful error

Storage Locations

Tokens are automatically saved to platform-specific locations with multi-tenant support:

Storage Directory:

Windows: C:\Users\{user}\AppData\Local\ms-graph-devtools\
Mac/Linux: ~/.config/ms-graph-devtools/

File Naming (Automatic):

With tenant+client: tokens.{tenantId}.{clientId}.json
Legacy/fallback: tokens.json

Example:

~/.config/ms-graph-devtools/
  ├── tokens.abc123-tenant.def456-client.json
  ├── tokens.xyz789-tenant.app2-client.json
  └── tokens.json  (fallback)

Benefits:

✅ Multiple tenants/clients supported automatically
✅ No overwrites when switching configurations
✅ Backward compatible with single-tenant setups
✅ Files created with secure permissions (owner read/write only)

📋 Usage Examples

Example 1: Global Configuration Pattern (Recommended)

// config/azure.ts - Configure once, use everywhere
import Azure from 'ms-graph-devtools';

Azure.config({
  clientId: process.env.AZURE_CLIENT_ID,
  clientSecret: process.env.AZURE_CLIENT_SECRET,
  tenantId: process.env.AZURE_TENANT_ID,
  refreshToken: process.env.AZURE_REFRESH_TOKEN,
});

export default Azure;

// anywhere in your app
import Azure from './config/azure';

await Azure.outlook.sendMail({...});
await Azure.teams.postMessage({...});

Example 2: Scheduled Automation

// scheduled-task.ts
import Azure from './config/azure'; // Pre-configured instance

async function dailyReport() {
  const emails = await Azure.outlook.getMails(
    new Date().toISOString(),
    "Invoice"
  );

  await Azure.outlook.sendMail({
    message: {
      subject: "Daily Report",
      body: {
        contentType: "Text",
        content: `Found ${emails.length} invoices today`,
      },
      toRecipients: [
        {
          emailAddress: { address: "admin@example.com" },
        },
      ],
    },
  });
}

dailyReport();

Add to cron:

0 9 * * * cd /path/to/project && node scheduled-task.js

Example 3: Token Provider with Playwright

// config/azure.ts
import Azure from "ms-graph-devtools";
import Playwright from "./playwright-helper";

Azure.config({
  clientId: process.env.AZURE_CLIENT_ID,
  clientSecret: process.env.AZURE_CLIENT_SECRET,
  tenantId: process.env.AZURE_TENANT_ID,
  tokenProvider: async (callback) => {
    // Playwright automates browser to get auth code
    return await Playwright.getAzureCode(callback);
  },
});

export default Azure;

// anywhere in your app
import Azure from './config/azure';

// Just works - tokenProvider handles auth automatically
await Azure.outlook.getMe();
await Azure.calendar.getCalendars();

Example 4: Multi-Tenant Usage

import Azure from "ms-graph-devtools";

// Company A
Azure.config({
  tenantId: "company-a-tenant-id",
  clientId: "app-1-client-id",
  clientSecret: process.env.COMPANY_A_SECRET,
  refreshToken: "company-a-token",
});
await Azure.outlook.getMe();
// Saved to: tokens.company-a-tenant-id.app-1-client-id.json

// Switch to Company B (reset first)
Azure.reset();
Azure.config({
  tenantId: "company-b-tenant-id",
  clientId: "app-2-client-id",
  clientSecret: process.env.COMPANY_B_SECRET,
  refreshToken: "company-b-token",
});
await Azure.teams.getTeams();
// Saved to: tokens.company-b-tenant-id.app-2-client-id.json

// Both token files are preserved!
// Switch between them by calling reset() and config()

Example 5: CI/CD Environment

// automation-script.js
import Azure from 'ms-graph-devtools';

// Load credentials from GitHub Secrets or environment
Azure.config({
  clientId: process.env.AZURE_CLIENT_ID,
  clientSecret: process.env.AZURE_CLIENT_SECRET,
  tenantId: process.env.AZURE_TENANT_ID,
  refreshToken: process.env.AZURE_REFRESH_TOKEN,
});

await Azure.outlook.sendMail({...});
await Azure.teams.postMessage({...});

# .github/workflows/automation.yml
steps:
  - run: node automation-script.js
    env:
      AZURE_REFRESH_TOKEN: ${{ secrets.AZURE_REFRESH_TOKEN }}
      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
      AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}

📚 Service Classes

This library provides specialized service classes for different Microsoft Graph APIs.

Two usage patterns:

Global instance (Recommended): Azure.outlook, Azure.teams, etc. after calling Azure.config()
Direct instantiation: new Outlook() for advanced use cases (multiple configs, dependency injection)

🔷 Outlook Service

Email operations with fluent builder pattern.

import Azure from "ms-graph-devtools";

// Pattern 1: Via Azure global instance (recommended)
const user = await Azure.outlook.getMe();

// Get emails
const emails = await Azure.outlook.getMails("2024-01-15", "invoice");

// Send email with fluent builder
await Azure.outlook
  .compose()
  .subject("Meeting Reminder")
  .body("Don't forget our meeting tomorrow!", "Text")
  .to(["colleague@example.com"])
  .cc(["manager@example.com"])
  .importance("high")
  .send();

// With attachments
await Azure.outlook
  .compose()
  .subject("Monthly Report")
  .body("<h1>Report</h1>", "HTML")
  .to(["boss@example.com"])
  .attachments(["./report.pdf", "./charts.xlsx"])
  .send();

// Pattern 2: Direct instantiation (advanced)
import { Outlook } from "ms-graph-devtools";
const outlook = new Outlook({ refreshToken: "..." });
await outlook.sendMail({...});

Available Methods:

getMe() - Get current user profile
sendMail(payload) - Send email (low-level)
getMails(date, subjectFilter?) - Get emails by date
compose() - Create fluent email builder

Email Builder Methods:

subject(text) - Set subject
body(content, type?) - Set body (Text/HTML)
to(recipients[]) - Set recipients
cc(recipients[]) - Set CC
bcc(recipients[]) - Set BCC
attachments(files[]) - Add attachments
importance(level) - Set priority (low/normal/high)
requestReadReceipt(bool) - Request read receipt
send() - Send the email

🔷 Teams Service

Teams messaging, adaptive cards, and channel management.

import Azure from "ms-graph-devtools";

// Get user's teams
const myTeams = await Azure.teams.getTeams();
// [{ id: '...', displayName: 'Engineering Team', description: '...' }]

// Get channels for a team
const channels = await Azure.teams.getChannels(myTeams[0].id);
// [{ id: '...', displayName: 'General', membershipType: 'standard' }]

// Get tags for mentions
const tags = await Azure.teams.getTags(myTeams[0].id);
// [{ id: '...', displayName: 'Backend Team', memberCount: 5 }]

// Send adaptive card with builder
await Azure.teams
  .compose()
  .team("team-id")
  .channel("channel-id")
  .card({
    type: "AdaptiveCard",
    version: "1.4",
    body: [
      {
        type: "TextBlock",
        text: "Deployment Complete!",
        size: "Large",
        weight: "Bolder",
      },
    ],
    actions: [
      {
        type: "Action.OpenUrl",
        title: "View Dashboard",
        url: "https://dashboard.example.com",
      },
    ],
  })
  .mentionTeam("team-id", "Engineering Team")
  .mentionUser("user-id", "John Doe")
  .send();

Available Methods:

getTeams() - Get all teams user has joined
getChannels(teamId) - Get channels in a team
getTags(teamId) - Get tags for mentions
postAdaptiveCard(teamId, channelId, card, tags?) - Post card (low-level)
compose() - Create fluent adaptive card builder

Adaptive Card Builder Methods:

team(teamId) - Set target team
channel(channelId) - Set target channel
card(adaptiveCard) - Set card JSON
mentionTeam(id, name) - Add team mention
mentionTag(id, name) - Add tag mention
mentionUser(id, name) - Add user mention
mentions(tags[]) - Add multiple mentions
send() - Post the card

🔷 SharePoint Service

SharePoint list operations and site management.

import Azure from "ms-graph-devtools";

// Search for sites
const sites = await Azure.sharePoint.searchSites("Engineering");
Azure.sharePoint.setSiteId(sites[0].id);

// Get all lists in site
const lists = await Azure.sharePoint.getLists();
// [{ id: '...', displayName: 'Tasks', webUrl: '...' }]

// Get list columns
const columns = await Azure.sharePoint.getListColumns("Tasks");

// Create list item
await Azure.sharePoint.createListItem("Tasks", {
  Title: "New Task",
  Status: "Active",
  Priority: "High",
  DueDate: "2024-12-31",
});

// Query items with filtering
const items = await Azure.sharePoint.getListItems("Tasks", {
  filter: "fields/Status eq 'Active'",
  orderby: "createdDateTime desc",
  top: 10,
  expand: "fields",
});

// Update item
await Azure.sharePoint.updateListItem("Tasks", "item-id", {
  Status: "Completed",
});

// Delete item
await Azure.sharePoint.deleteListItem("Tasks", "item-id");

// Advanced: Query and process (task queue pattern)
const tasks = await Azure.sharePoint.queryAndProcess(
  "TaskQueue",
  "fields/taskName eq 'send-notification'",
  (item) => ({
    id: item.id,
    recipient: item.fields.recipient,
    message: item.fields.message,
  }),
  true // delete after processing
);

// Get latest item
const latest = await Azure.sharePoint.getLatestItem("Tasks");

Available Methods:

setSiteId(siteId) - Set default site ID
searchSites(query) - Search for sites
getSiteByPath(hostname, path) - Get specific site
getLists(siteId?) - Get all lists
getList(listId, siteId?) - Get specific list
getListColumns(listId, siteId?) - Get list columns
getListItems(listId, options?, siteId?) - Query list items
getListItem(listId, itemId, expand?, siteId?) - Get single item
createListItem(listId, fields, siteId?) - Create item
updateListItem(listId, itemId, fields, siteId?) - Update item
deleteListItem(listId, itemId, siteId?) - Delete item
deleteListItems(listId, itemIds[], siteId?) - Bulk delete
queryAndProcess(listId, filter, processor, deleteAfter?, siteId?) - Query and process pattern
getLatestItem(listId, orderBy?, filter?, siteId?) - Get most recent item

🔷 Calendar Service

Calendar and holiday management.

import Azure from "ms-graph-devtools";

// Get all calendars
const calendars = await Azure.calendar.getCalendars();

// Get holidays
const indiaHolidays = await Azure.calendar.getIndiaHolidays(
  "2024-01-01",
  "2024-12-31"
);
const japanHolidays = await Azure.calendar.getJapanHolidays(
  "2024-01-01",
  "2024-12-31"
);

Available Methods:

getCalendars() - Get user's calendars
getIndiaHolidays(start, end) - Get India holidays
getJapanHolidays(start, end) - Get Japan holidays

🎯 Service Usage Patterns

Pattern 1: Global Instance (Recommended)

// config/azure.ts
import Azure from 'ms-graph-devtools';

Azure.config({
  clientId: process.env.AZURE_CLIENT_ID,
  clientSecret: process.env.AZURE_CLIENT_SECRET,
  tenantId: process.env.AZURE_TENANT_ID,
  refreshToken: process.env.AZURE_REFRESH_TOKEN,
});

export default Azure;

// anywhere in your app
import Azure from './config/azure';

await Azure.outlook.compose().subject('Test').to(['user@example.com']).send();
await Azure.teams.compose().team('id').channel('id').card({...}).send();
await Azure.sharePoint.createListItem('Tasks', { Title: 'New Task' });

Pattern 2: Direct Service Instantiation (Advanced)

For cases where you need multiple configurations or dependency injection:

import { Outlook, Teams } from "ms-graph-devtools";

const outlook = new Outlook({
  clientId: process.env.AZURE_CLIENT_ID,
  clientSecret: process.env.AZURE_CLIENT_SECRET,
  tenantId: process.env.AZURE_TENANT_ID,
  refreshToken: process.env.AZURE_REFRESH_TOKEN,
});

const teams = new Teams(); // Uses global config

Pattern 3: Shared Authentication

import { AzureAuth, Outlook, Teams } from "ms-graph-devtools";

// Create shared auth instance
const auth = new AzureAuth({ refreshToken: "your-token" });

// Share across services
const outlook = new Outlook(auth);
const teams = new Teams(auth);

await outlook.getMe();
await teams.getTeams();

Pattern 4: Task Automation

import Azure from './config/azure';

// Process task queue
const tasks = await Azure.sharePoint.queryAndProcess(
  "NotificationQueue",
  "fields/status eq 'pending'",
  async (item) => {
    // Send notification to Teams
    await Azure.teams
      .compose()
      .team(item.fields.teamId)
      .channel(item.fields.channelId)
      .card(JSON.parse(item.fields.cardData))
      .send();

    return { id: item.id, processed: true };
  },
  true // delete after processing
);

console.log(`Processed ${tasks.length} notifications`);

💡 Best Practices

1. Use Global Instance Export Pattern

The recommended way to use this library:

// ✅ GOOD: Single config file pattern
// config/azure.ts
import Azure from 'ms-graph-devtools';

Azure.config({
  clientId: process.env.AZURE_CLIENT_ID,
  clientSecret: process.env.AZURE_CLIENT_SECRET,
  tenantId: process.env.AZURE_TENANT_ID,
  tokenProvider: async (callback) => await getAuthCode(callback),
});

export default Azure;

// Everywhere else in your app
import Azure from './config/azure';
await Azure.outlook.sendMail({...});

Why this is best:

Single source of truth for configuration
No config duplication across files
Easier to maintain and update credentials
Consistent authentication across entire app
Simpler imports (just the instance, no config needed)

Avoid this pattern:

// ❌ BAD: Repeating config everywhere
import { Outlook } from 'ms-graph-devtools';

const outlook = new Outlook({
  clientId: process.env.AZURE_CLIENT_ID,  // Repeated in every file
  clientSecret: process.env.AZURE_CLIENT_SECRET,
  tenantId: process.env.AZURE_TENANT_ID,
  refreshToken: process.env.AZURE_REFRESH_TOKEN,
});

2. Keep Config Separate from Business Logic

File structure:

your-project/
├── config/
│   └── azure.ts          # Azure config + export
├── src/
│   ├── email.ts          # import Azure from '../config/azure'
│   ├── notifications.ts  # import Azure from '../config/azure'
│   └── reports.ts        # import Azure from '../config/azure'
└── .env                  # Credentials (gitignored)

3. Use Environment Variables

Always load credentials from environment variables, never hardcode:

// config/azure.ts
import Azure from 'ms-graph-devtools';
import 'dotenv/config'; // If using dotenv

Azure.config({
  clientId: process.env.AZURE_CLIENT_ID!,
  clientSecret: process.env.AZURE_CLIENT_SECRET!,
  tenantId: process.env.AZURE_TENANT_ID!,
  tokenProvider: async (callback) => await getAuthCode(callback),
});

export default Azure;

4. Type Safety with TypeScript

// config/azure.ts
import Azure from 'ms-graph-devtools';

// Validate required env vars at startup
const requiredEnvVars = ['AZURE_CLIENT_ID', 'AZURE_CLIENT_SECRET', 'AZURE_TENANT_ID'];
for (const envVar of requiredEnvVars) {
  if (!process.env[envVar]) {
    throw new Error(`Missing required environment variable: ${envVar}`);
  }
}

Azure.config({
  clientId: process.env.AZURE_CLIENT_ID!,
  clientSecret: process.env.AZURE_CLIENT_SECRET!,
  tenantId: process.env.AZURE_TENANT_ID!,
  tokenProvider: async (callback) => await getAuthCode(callback),
});

export default Azure;

🔒 Security Best Practices

1. Never Commit Tokens

Add to .gitignore:

.env
tokens.json
*.token

2. Use Secrets in CI/CD

Store credentials as GitHub Secrets or CI/CD environment variables and pass them explicitly to the library:

const outlook = new Outlook({
  clientId: process.env.AZURE_CLIENT_ID,
  clientSecret: process.env.AZURE_CLIENT_SECRET,
  tenantId: process.env.AZURE_TENANT_ID,
  refreshToken: process.env.AZURE_REFRESH_TOKEN,
});

3. Secure File Permissions

The utility automatically sets secure permissions on token files:

Directory: 0o700 (owner only)
File: 0o600 (owner read/write only)

4. Token Rotation

Refresh tokens typically expire after 90 days. Set a reminder to rotate them.

5. Least Privilege

Only request the scopes you need in your Azure App Registration.

🛠️ Getting Your Refresh Token

See get-refresh-token.js for an interactive tool to obtain your refresh token.

node get-refresh-token.js

Or see REFRESH_TOKEN_SETUP.md for manual instructions.

❓ FAQ

Q: What's the recommended way to use this library?

A: Export a configured global instance - this is the best practice for 95% of use cases:

// config/azure.ts - Configure once
import Azure from 'ms-graph-devtools';
Azure.config({...});
export default Azure;

// everywhere else - just import and use
import Azure from './config/azure';
await Azure.outlook.sendMail({...});

This gives you:

Single source of truth
No config duplication
Clean imports everywhere
Easy to maintain

Q: Do I need to call Azure.config() every time I use a service?

A: No! That's the beauty of the global instance pattern. Call Azure.config() once in a config file, export the instance, then import and use it everywhere.

// config/azure.ts - Call config() ONCE
Azure.config({...});
export default Azure;

// other files - NO config() needed, just import
import Azure from './config/azure';
await Azure.outlook.sendMail({...});
await Azure.teams.postMessage({...});

Q: What if I call config() multiple times with different tokens?

A: Each call to config() replaces the previous configuration and resets all service instances. Use Azure.reset() first for clarity.

Q: Where are tokens stored?

A: Platform-specific secure locations:

Windows: %LOCALAPPDATA%\ms-graph-devtools\tokens.json
Mac/Linux: ~/.config/ms-graph-devtools/tokens.json

Q: Can I use this in serverless/Lambda?

A: Yes! Use a custom tokenProvider that fetches from your secret store (AWS Secrets Manager, etc.).

Q: Will this work with my organization's SSO (Okta, 1Password, etc.)?

A: Yes! You obtain the refresh token once through your SSO, then the utility handles everything automatically.

Q: How do I update the token?

A: Either:

Azure.reset() then Azure.config({ refreshToken: 'new-token' })
Delete the storage file and call Azure.config() with new credentials

🐛 Troubleshooting

"No refresh token available"

Solution: Provide a token via Azure.config():

Azure.config({ refreshToken: 'xxx' })
// OR
Azure.config({ tokenProvider: async (callback) => getAuthCode(callback) })
// OR
Azure.config({ accessToken: 'xxx' }) // Light mode

"Invalid grant" error

Your refresh token has expired (typically 90 days). Get a new one:

node get-refresh-token.js

"Insufficient privileges"

Your Azure App Registration needs API permissions. Go to: Azure Portal → App Registrations → API permissions → Add permissions

Storage file not found

Normal on first run. The file is created when you first provide a token.

📦 For Package Publishers

When publishing to npm:

Remove Playwright dependency (user-specific auth)
Include get-refresh-token.js helper script
Document in README how users get their token
Add to bin in package.json:

{
  "bin": {
    "get-refresh-token": "./get-refresh-token.js"
  }
}

Users can then run:

npx your-package get-refresh-token

📄 License

MIT

🤝 Contributing

Contributions welcome! Please open an issue first for major changes.

Built with ❤️ for automated Microsoft Graph workflows

Name		Name	Last commit message	Last commit date
Latest commit History 39 Commits
.claude		.claude
.github		.github
dev-notes		dev-notes
examples		examples
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
index.d.ts		index.d.ts
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

License

oharu121/ms-graph-devtools

Folders and files

Latest commit

History

Repository files navigation

Azure Microsoft Graph Utility

✨ Features

Major Achievement: Three-Tier User System

Tier 1: Light User (Access Token Only)

Tier 2: Medium User (Refresh Token)

Tier 3: Super User (Token Provider)

🚀 Quick Start

Installation

Best Practice: Global Instance Pattern (Recommended)

📖 API Reference

Azure.config(config): void

Service Getters

Azure.reset(): void

Azure.listStoredCredentials(): Promise<Array>

Azure.clearStoredCredentials(tenantId?, clientId?): Promise<void>

🔑 Token Management

Token Priority

Storage Locations

📋 Usage Examples

Example 1: Global Configuration Pattern (Recommended)

Example 2: Scheduled Automation

Example 3: Token Provider with Playwright

Example 4: Multi-Tenant Usage

Example 5: CI/CD Environment

📚 Service Classes

🔷 Outlook Service

🔷 Teams Service

🔷 SharePoint Service

🔷 Calendar Service

🎯 Service Usage Patterns

Pattern 1: Global Instance (Recommended)

Pattern 2: Direct Service Instantiation (Advanced)

Pattern 3: Shared Authentication

Pattern 4: Task Automation

💡 Best Practices

1. Use Global Instance Export Pattern

2. Keep Config Separate from Business Logic

3. Use Environment Variables

4. Type Safety with TypeScript

🔒 Security Best Practices

1. Never Commit Tokens

2. Use Secrets in CI/CD

3. Secure File Permissions

4. Token Rotation

5. Least Privilege

🛠️ Getting Your Refresh Token

❓ FAQ

🐛 Troubleshooting

"No refresh token available"

"Invalid grant" error

"Insufficient privileges"

Storage file not found

📦 For Package Publishers

📄 License

🤝 Contributing

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Contributors 2

Uh oh!

Languages

`Azure.config(config): void`

`Azure.reset(): void`

`Azure.listStoredCredentials(): Promise<Array>`

`Azure.clearStoredCredentials(tenantId?, clientId?): Promise<void>`

Packages