Microsoft Graph Api

#!/usr/bin/env bun
/**
 * Microsoft Graph Authentication Script
 *
 * Manual authentication and credential management.
 * Note: For normal use, authentication is handled automatically by
 * emails.ts and calendar.ts - this script is only needed for:
 * - Listing credential profiles
 * - Deleting credential profiles
 * - Interactive authentication with custom Azure AD apps
 *
 * Usage:
 *   bun run auth.ts [--profile <name>] [--client-id <id>] [--tenant-id <id>]
 *
 * Options:
 *   --profile     Credential profile name (default: "default")
 *   --client-id   Azure AD application (client) ID
 *   --tenant-id   Azure AD tenant ID (default: "common" for multi-tenant)
 *   --scopes      Comma-separated list of scopes (default: all scopes)
 *   --list        List all stored credential profiles
 *   --delete      Delete a credential profile
 *
 * Examples:
 *   bun run auth.ts --list
 *   bun run auth.ts --delete --profile old-account
 *   bun run auth.ts --client-id your-app-id --tenant-id your-tenant-id
 */

import { parseArgs } from "util";
import { PublicClientApplication } from "@azure/msal-node";
import { GRAPH_SCOPES } from "./lib/graph-client";
import {
  listProfiles,
  getCredential,
  setCredential,
  deleteCredential,
} from "./lib/credentials";
import type { Credential } from "./lib/types";

const DEFAULT_CLIENT_ID = "14d82eec-204b-4c2f-b7e8-296a70dab67e";
const DEFAULT_TENANT = "common";

const { values } = parseArgs({
  args: Bun.argv.slice(2),
  options: {
    profile: { type: "string", default: "default" },
    "client-id": { type: "string" },
    "tenant-id": { type: "string" },
    scopes: { type: "string" },
    list: { type: "boolean", default: false },
    delete: { type: "boolean", default: false },
    help: { type: "boolean", short: "h", default: false },
  },
});

if (values.help) {
  console.log(`
Microsoft Graph Authentication

Usage:
  bun run auth.ts [options]

Options:
  --profile <name>      Credential profile name (default: "default")
  --client-id <id>      Azure AD application (client) ID
  --tenant-id <id>      Azure AD tenant ID (default: "common" for multi-tenant)
  --scopes <scopes>     Comma-separated list of scopes
  --list                List all stored credential profiles
  --delete              Delete a credential profile
  -h, --help            Show this help message

Note:
  For normal email and calendar access, authentication is handled automatically.
  This script is only needed for managing profiles or using custom Azure AD apps.

Using Your Own App Registration:
  1. Go to https://portal.azure.com
  2. Navigate to Azure Active Directory > App registrations
  3. Create a new registration:
     - Name: Your app name
     - Supported account types: Choose based on your needs
     - Redirect URI: Select "Public client/native" and add:
       https://login.microsoftonline.com/common/oauth2/nativeclient
  4. Go to "Authentication" and enable "Allow public client flows"
  5. Go to "API permissions" and add:
     - Microsoft Graph > Delegated > Mail.Read
     - Microsoft Graph > Delegated > Calendars.Read
     - Microsoft Graph > Delegated > User.Read
  6. Copy the "Application (client) ID" from Overview
  7. Use it with: --client-id your-app-id

Examples:
  # List all profiles
  bun run auth.ts --list

  # Delete a profile
  bun run auth.ts --delete --profile old

  # Authenticate with your own app
  bun run auth.ts --client-id 12345678-1234-1234-1234-123456789abc

  # Authenticate with single-tenant app
  bun run auth.ts --client-id your-app-id --tenant-id your-tenant-id
`);
  process.exit(0);
}

async function main() {
  if (values.list) {
    const profiles = await listProfiles("microsoft-graph");
    if (profiles.length === 0) {
      console.log("No credential profiles found.");
      console.log("Authentication is handled automatically when using email or calendar scripts.");
    } else {
      console.log("Microsoft Graph credential profiles:\n");
      for (const profile of profiles) {
        const cred = await getCredential("microsoft-graph", profile);
        if (cred) {
          const expired = new Date(cred.expiresAt) < new Date();
          console.log(`  ${profile}:`);
          console.log(`    Account: ${cred.account}`);
          console.log(`    Scopes: ${cred.scopes.join(", ")}`);
          if (cred.clientId) {
            console.log(`    Client ID: ${cred.clientId}`);
          }
          if (cred.tenantId) {
            console.log(`    Tenant ID: ${cred.tenantId}`);
          }
          console.log(`    Token Status: ${expired ? "EXPIRED (will refresh)" : "Valid"}`);
          console.log();
        }
      }
    }
    return;
  }

  if (values.delete) {
    const deleted = await deleteCredential("microsoft-graph", values.profile!);
    if (deleted) {
      console.log(`Deleted credential profile: ${values.profile}`);
    } else {
      console.log(`Profile not found: ${values.profile}`);
    }
    return;
  }

  // Interactive authentication
  const scopes = values.scopes
    ? values.scopes.split(",").map((s) => s.trim())
    : [...GRAPH_SCOPES.user, ...GRAPH_SCOPES.mail, ...GRAPH_SCOPES.calendar];

  const clientId = values["client-id"] ?? DEFAULT_CLIENT_ID;
  const tenantId = values["tenant-id"] ?? DEFAULT_TENANT;

  console.log(`Authenticating with Microsoft Graph...`);
  console.log(`Profile: ${values.profile}`);
  if (values["client-id"]) {
    console.log(`Client ID: ${clientId}`);
  } else {
    console.log(`Client ID: (using default Graph Explorer client)`);
  }
  if (values["tenant-id"]) {
    console.log(`Tenant ID: ${tenantId}`);
  }
  console.log(`Scopes: ${scopes.join(", ")}\n`);

  try {
    const pca = new PublicClientApplication({
      auth: {
        clientId,
        authority: `https://login.microsoftonline.com/${tenantId}`,
      },
    });

    const result = await pca.acquireTokenByDeviceCode({
      scopes,
      deviceCodeCallback: (response) => {
        console.log(`\nTo authenticate, please:`);
        console.log(`1. Go to: ${response.verificationUri}`);
        console.log(`2. Enter code: ${response.userCode}`);
        console.log(`\nWaiting for authentication...`);
      },
    });

    if (result) {
      const credential: Credential = {
        accessToken: result.accessToken,
        refreshToken: (result as any).refreshToken ?? "",
        expiresAt: result.expiresOn?.toISOString() ?? new Date(Date.now() + 3600000).toISOString(),
        account: result.account?.username ?? "unknown",
        scopes: result.scopes?.length > 0 ? result.scopes : scopes,
        clientId: values["client-id"] ? clientId : undefined,
        tenantId: values["tenant-id"] ? tenantId : undefined,
      };

      await setCredential("microsoft-graph", values.profile!, credential);

      console.log("\nAuthentication successful!");
      console.log(`  Account: ${credential.account}`);
      console.log(`  Expires: ${new Date(credential.expiresAt).toLocaleString()}`);
      console.log(`\nCredentials saved to profile: ${values.profile}`);
    }
  } catch (error) {
    console.error("Authentication failed:", error);
    process.exit(1);
  }
}

main();

#!/usr/bin/env bun
/**
 * Microsoft Graph Calendar Script
 *
 * View, search, and create calendar events via Microsoft Graph API.
 * Authentication is handled automatically - if needed, returns auth instructions.
 *
 * Usage:
 *   bun run calendar.ts <command> [options]
 *
 * Commands:
 *   list      List upcoming calendar events
 *   view      View a specific event by ID
 *   search    Search calendar events
 *   today     Show today's events
 *   week      Show this week's events
 *   create    Create a new calendar event
 *
 * Options:
 *   --profile    Credential profile (default: "default")
 *   --top        Number of results (default: 10)
 *   --start      Start date/time (ISO format or relative: today, tomorrow)
 *   --end        End date/time (ISO format or relative: +7d, +1m)
 *   --query      Search query for 'search' command
 *   --id         Event ID for 'view' command
 *   --subject    Event subject/title for 'create'
 *   --location   Event location for 'create'
 *   --body       Event description for 'create'
 *   --attendees  Attendee emails for 'create' (comma-separated)
 *   --all-day    Create as all-day event
 *
 * Output:
 *   Always JSON with structure:
 *   - Success: { "status": "success", "data": [...] }
 *   - Auth needed: { "status": "auth_required", "userCode": "...", "verificationUri": "..." }
 *   - Error: { "status": "error", "error": "..." }
 */

import { parseArgs } from "util";
import { GRAPH_SCOPES } from "./lib/graph-client";
import { ensureAuth, type ScriptResponse } from "./lib/auth-handler";
import type { GraphCalendarEvent } from "./lib/types";

const { values, positionals } = parseArgs({
  args: Bun.argv.slice(2),
  options: {
    profile: { type: "string", default: "default" },
    top: { type: "string", default: "10" },
    start: { type: "string" },
    end: { type: "string" },
    query: { type: "string" },
    id: { type: "string" },
    subject: { type: "string" },
    location: { type: "string" },
    body: { type: "string" },
    attendees: { type: "string" },
    "all-day": { type: "boolean", default: false },
    help: { type: "boolean", short: "h", default: false },
  },
  allowPositionals: true,
});

const command = positionals[0] || "list";

if (values.help) {
  console.log(`
Microsoft Graph Calendar Access

Usage:
  bun run calendar.ts <command> [options]

Commands:
  list      List upcoming calendar events (default)
  view      View a specific event by ID
  search    Search calendar events
  today     Show today's events
  week      Show this week's events
  create    Create a new calendar event

Options:
  --profile <name>    Credential profile (default: "default")
  --top <n>           Number of results (default: 10)
  --start <date>      Start date/time (ISO format or: today, tomorrow, +1d)
  --end <date>        End date/time (ISO format or: +7d, +1m, +1y)
  --query <q>         Search query (for 'search' command)
  --id <id>           Event ID (for 'view' command)
  --subject <text>    Event subject/title (for 'create')
  --location <text>   Event location (for 'create')
  --body <text>       Event description (for 'create')
  --attendees <list>  Attendee emails, comma-separated (for 'create')
  --all-day           Create as all-day event
  -h, --help          Show this help message

Output:
  JSON with status field indicating success, auth_required, auth_pending, or error.

Date/Time Examples:
  --start today --end +7d                       Next 7 days
  --start 2024-01-01 --end 2024-01-31
  --start tomorrow
  --start 2024-01-15T14:00:00 --end 2024-01-15T15:00:00

Examples:
  bun run calendar.ts                           # List upcoming events
  bun run calendar.ts today                     # Today's events
  bun run calendar.ts week                      # This week's events
  bun run calendar.ts list --start tomorrow --end +7d
  bun run calendar.ts search --query "1:1"
  bun run calendar.ts view --id AAMkAG...
  bun run calendar.ts create --subject "Team Meeting" --start 2024-01-15T14:00:00 --end 2024-01-15T15:00:00
  bun run calendar.ts create --subject "Review" --start tomorrow --end +1d --attendees "a@ex.com,b@ex.com"
  bun run calendar.ts create --subject "Holiday" --start 2024-12-25 --all-day
`);
  process.exit(0);
}

function output<T>(response: ScriptResponse<T>): void {
  console.log(JSON.stringify(response));
  process.exit(response.status === "success" ? 0 : 1);
}

async function graphRequest<T>(token: string, endpoint: string): Promise<T> {
  const url = `https://graph.microsoft.com/v1.0${endpoint}`;

  const response = await fetch(url, {
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
  });

  if (!response.ok) {
    const error = await response.text();
    throw new Error(`Graph API error: ${response.status} - ${error}`);
  }

  return response.json();
}

async function graphPost<T>(token: string, endpoint: string, body: unknown): Promise<T> {
  const url = `https://graph.microsoft.com/v1.0${endpoint}`;

  const response = await fetch(url, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  if (!response.ok) {
    const error = await response.text();
    throw new Error(`Graph API error: ${response.status} - ${error}`);
  }

  return response.json();
}

function parseAttendees(input: string): Array<{ emailAddress: { address: string }; type: string }> {
  return input
    .split(",")
    .map((email) => email.trim())
    .filter((email) => email.length > 0)
    .map((address) => ({
      emailAddress: { address },
      type: "required",
    }));
}

function parseDate(input: string, baseDate: Date = new Date()): Date {
  const lower = input.toLowerCase();

  if (lower === "today") {
    const d = new Date(baseDate);
    d.setHours(0, 0, 0, 0);
    return d;
  }

  if (lower === "tomorrow") {
    const d = new Date(baseDate);
    d.setDate(d.getDate() + 1);
    d.setHours(0, 0, 0, 0);
    return d;
  }

  // Relative dates: +7d, +1m, +1y
  const relativeMatch = lower.match(/^\+(\d+)([dmy])$/);
  if (relativeMatch) {
    const [, amount, unit] = relativeMatch;
    const d = new Date(baseDate);
    switch (unit) {
      case "d":
        d.setDate(d.getDate() + parseInt(amount));
        break;
      case "m":
        d.setMonth(d.getMonth() + parseInt(amount));
        break;
      case "y":
        d.setFullYear(d.getFullYear() + parseInt(amount));
        break;
    }
    return d;
  }

  // ISO date
  return new Date(input);
}

function formatEventData(event: GraphCalendarEvent) {
  return {
    id: event.id,
    subject: event.subject,
    start: event.start,
    end: event.end,
    isAllDay: event.isAllDay ?? false,
    location: event.location?.displayName ?? null,
    organizer: event.organizer?.emailAddress ?? null,
    attendees: event.attendees?.map((a) => ({
      email: a.emailAddress,
      status: a.status?.response ?? null,
    })) ?? [],
    bodyPreview: event.bodyPreview ?? null,
  };
}

async function main() {
  // Determine required scopes based on command
  const requiredScopes = [...GRAPH_SCOPES.user];
  if (command === "create") {
    requiredScopes.push(...GRAPH_SCOPES.calendarWrite);
  } else {
    requiredScopes.push(...GRAPH_SCOPES.calendar);
  }

  // Ensure we're authenticated
  const auth = await ensureAuth({
    service: "microsoft-graph",
    profile: values.profile!,
    requiredScopes,
  });

  if (!auth.ok) {
    output(auth.response);
    return;
  }

  const token = auth.token;
  const top = parseInt(values.top!, 10);

  // Determine date range based on command
  let startDate: Date;
  let endDate: Date;

  const now = new Date();

  switch (command) {
    case "today":
      startDate = new Date(now);
      startDate.setHours(0, 0, 0, 0);
      endDate = new Date(now);
      endDate.setHours(23, 59, 59, 999);
      break;

    case "week":
      startDate = new Date(now);
      startDate.setHours(0, 0, 0, 0);
      endDate = new Date(now);
      endDate.setDate(endDate.getDate() + 7);
      break;

    default:
      startDate = values.start ? parseDate(values.start) : now;
      endDate = values.end ? parseDate(values.end, startDate) : parseDate("+30d", startDate);
  }

  try {
    switch (command) {
      case "list":
      case "today":
      case "week": {
        const startISO = startDate.toISOString();
        const endISO = endDate.toISOString();

        const response = await graphRequest<{ value: GraphCalendarEvent[] }>(
          token,
          `/me/calendarView?startDateTime=${startISO}&endDateTime=${endISO}&$top=${top}&$orderby=start/dateTime`
        );

        output({
          status: "success",
          data: response.value.map(formatEventData),
        });
        break;
      }

      case "view": {
        if (!values.id) {
          output({ status: "error", error: "--id is required for 'view' command" });
          return;
        }

        const event = await graphRequest<GraphCalendarEvent>(
          token,
          `/me/events/${values.id}`
        );

        output({
          status: "success",
          data: formatEventData(event),
        });
        break;
      }

      case "search": {
        if (!values.query) {
          output({ status: "error", error: "--query is required for 'search' command" });
          return;
        }

        // Use filter instead of search for calendar (search not supported on events)
        const query = values.query.replace(/'/g, "''");
        const response = await graphRequest<{ value: GraphCalendarEvent[] }>(
          token,
          `/me/events?$filter=contains(subject,'${query}')&$top=${top}&$orderby=start/dateTime desc`
        );

        output({
          status: "success",
          data: response.value.map(formatEventData),
        });
        break;
      }

      case "create": {
        if (!values.subject) {
          output({ status: "error", error: "--subject is required for 'create' command" });
          return;
        }
        if (!values.start) {
          output({ status: "error", error: "--start is required for 'create' command" });
          return;
        }

        const isAllDay = values["all-day"];
        const eventStart = parseDate(values.start);
        const eventEnd = values.end
          ? parseDate(values.end, eventStart)
          : isAllDay
            ? new Date(eventStart.getTime() + 24 * 60 * 60 * 1000) // Next day for all-day
            : new Date(eventStart.getTime() + 60 * 60 * 1000); // 1 hour default

        // Get timezone
        const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;

        const eventBody: {
          subject: string;
          start: { dateTime: string; timeZone: string };
          end: { dateTime: string; timeZone: string };
          isAllDay?: boolean;
          location?: { displayName: string };
          body?: { contentType: string; content: string };
          attendees?: Array<{ emailAddress: { address: string }; type: string }>;
        } = {
          subject: values.subject,
          start: {
            dateTime: isAllDay
              ? eventStart.toISOString().split("T")[0]
              : eventStart.toISOString(),
            timeZone,
          },
          end: {
            dateTime: isAllDay
              ? eventEnd.toISOString().split("T")[0]
              : eventEnd.toISOString(),
            timeZone,
          },
        };

        if (isAllDay) {
          eventBody.isAllDay = true;
        }

        if (values.location) {
          eventBody.location = { displayName: values.location };
        }

        if (values.body) {
          eventBody.body = { contentType: "Text", content: values.body };
        }

        if (values.attendees) {
          eventBody.attendees = parseAttendees(values.attendees);
        }

        const createdEvent = await graphPost<GraphCalendarEvent>(
          token,
          "/me/events",
          eventBody
        );

        output({
          status: "success",
          data: formatEventData(createdEvent),
        });
        break;
      }

      default:
        output({ status: "error", error: `Unknown command: ${command}. Use --help for usage.` });
    }
  } catch (error) {
    output({
      status: "error",
      error: error instanceof Error ? error.message : "Unknown error",
    });
  }
}

main();

#!/usr/bin/env bun
/**
 * Microsoft Graph Email Script
 *
 * Read, list, search, and send emails via Microsoft Graph API.
 * Authentication is handled automatically - if needed, returns auth instructions.
 *
 * Usage:
 *   bun run emails.ts <command> [options]
 *
 * Commands:
 *   list      List emails from a folder
 *   read      Read a specific email by ID
 *   search    Search emails
 *   folders   List mail folders
 *   send      Send an email
 *
 * Options:
 *   --profile    Credential profile (default: "default")
 *   --folder     Folder name or ID (default: "inbox")
 *   --top        Number of results (default: 10)
 *   --query      Search query for 'search' command
 *   --id         Email ID for 'read' command
 *   --to         Recipient email(s) for 'send' (comma-separated)
 *   --cc         CC recipient(s) for 'send' (comma-separated)
 *   --bcc        BCC recipient(s) for 'send' (comma-separated)
 *   --subject    Email subject for 'send'
 *   --body       Email body for 'send'
 *   --html       Send body as HTML (default: plain text)
 *
 * Output:
 *   Always JSON with structure:
 *   - Success: { "status": "success", "data": [...] }
 *   - Auth needed: { "status": "auth_required", "userCode": "...", "verificationUri": "..." }
 *   - Error: { "status": "error", "error": "..." }
 */

import { parseArgs } from "util";
import { GRAPH_SCOPES } from "./lib/graph-client";
import { ensureAuth, type ScriptResponse } from "./lib/auth-handler";
import type { GraphEmail, MailFolder } from "./lib/types";

const { values, positionals } = parseArgs({
  args: Bun.argv.slice(2),
  options: {
    profile: { type: "string", default: "default" },
    folder: { type: "string", default: "inbox" },
    top: { type: "string", default: "10" },
    query: { type: "string" },
    id: { type: "string" },
    to: { type: "string" },
    cc: { type: "string" },
    bcc: { type: "string" },
    subject: { type: "string" },
    body: { type: "string" },
    html: { type: "boolean", default: false },
    help: { type: "boolean", short: "h", default: false },
  },
  allowPositionals: true,
});

const command = positionals[0];

if (values.help) {
  console.log(`
Microsoft Graph Email Access

Usage:
  bun run emails.ts <command> [options]

Commands:
  list      List emails from a folder
  read      Read a specific email by ID
  search    Search emails
  folders   List mail folders
  send      Send an email

Options:
  --profile <name>    Credential profile (default: "default")
  --folder <name>     Folder name or ID (default: "inbox")
  --top <n>           Number of results (default: 10)
  --query <q>         Search query (for 'search' command)
  --id <id>           Email ID (for 'read' command)
  --to <emails>       Recipient email(s), comma-separated (for 'send')
  --cc <emails>       CC recipient(s), comma-separated (for 'send')
  --bcc <emails>      BCC recipient(s), comma-separated (for 'send')
  --subject <text>    Email subject (for 'send')
  --body <text>       Email body (for 'send')
  --html              Send body as HTML instead of plain text
  -h, --help          Show this help message

Output:
  JSON with status field indicating success, auth_required, auth_pending, or error.

Search Query Examples:
  from:sender@example.com
  subject:meeting
  hasAttachments:true
  received>=2024-01-01
  "exact phrase"

Examples:
  bun run emails.ts list
  bun run emails.ts list --folder "Sent Items" --top 5
  bun run emails.ts read --id AAMkAG...
  bun run emails.ts search --query "from:boss@company.com subject:urgent"
  bun run emails.ts folders
  bun run emails.ts send --to "user@example.com" --subject "Hello" --body "Hi there!"
  bun run emails.ts send --to "a@ex.com,b@ex.com" --cc "c@ex.com" --subject "Team Update" --body "<h1>Update</h1>" --html
`);
  process.exit(0);
}

function output<T>(response: ScriptResponse<T>): void {
  console.log(JSON.stringify(response));
  process.exit(response.status === "success" ? 0 : 1);
}

async function graphRequest<T>(token: string, endpoint: string): Promise<T> {
  const url = `https://graph.microsoft.com/v1.0${endpoint}`;

  const response = await fetch(url, {
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
  });

  if (!response.ok) {
    const error = await response.text();
    throw new Error(`Graph API error: ${response.status} - ${error}`);
  }

  return response.json();
}

async function graphPost(token: string, endpoint: string, body: unknown): Promise<void> {
  const url = `https://graph.microsoft.com/v1.0${endpoint}`;

  const response = await fetch(url, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  if (!response.ok) {
    const error = await response.text();
    throw new Error(`Graph API error: ${response.status} - ${error}`);
  }
}

function parseRecipients(input: string): Array<{ emailAddress: { address: string } }> {
  return input
    .split(",")
    .map((email) => email.trim())
    .filter((email) => email.length > 0)
    .map((address) => ({ emailAddress: { address } }));
}

async function main() {
  if (!command) {
    output({ status: "error", error: "No command specified. Use --help for usage." });
    return;
  }

  // Determine required scopes based on command
  const requiredScopes = [...GRAPH_SCOPES.user];
  if (command === "send") {
    requiredScopes.push(...GRAPH_SCOPES.mailSend);
  } else {
    requiredScopes.push(...GRAPH_SCOPES.mail);
  }

  // Ensure we're authenticated
  const auth = await ensureAuth({
    service: "microsoft-graph",
    profile: values.profile!,
    requiredScopes,
  });

  if (!auth.ok) {
    output(auth.response);
    return;
  }

  const token = auth.token;
  const top = parseInt(values.top!, 10);

  try {
    switch (command) {
      case "list": {
        const folder = encodeURIComponent(values.folder!);
        const response = await graphRequest<{ value: GraphEmail[] }>(
          token,
          `/me/mailFolders/${folder}/messages?$top=${top}&$orderby=receivedDateTime desc`
        );

        output({
          status: "success",
          data: response.value.map((email) => ({
            id: email.id,
            subject: email.subject,
            from: email.from.emailAddress,
            receivedDateTime: email.receivedDateTime,
            bodyPreview: email.bodyPreview,
            isRead: email.isRead,
            hasAttachments: email.hasAttachments,
          })),
        });
        break;
      }

      case "read": {
        if (!values.id) {
          output({ status: "error", error: "--id is required for 'read' command" });
          return;
        }

        const email = await graphRequest<GraphEmail>(
          token,
          `/me/messages/${values.id}?$select=id,subject,from,receivedDateTime,body,bodyPreview,isRead,hasAttachments`
        );

        output({
          status: "success",
          data: {
            id: email.id,
            subject: email.subject,
            from: email.from.emailAddress,
            receivedDateTime: email.receivedDateTime,
            body: email.body,
            bodyPreview: email.bodyPreview,
            isRead: email.isRead,
            hasAttachments: email.hasAttachments,
          },
        });
        break;
      }

      case "search": {
        if (!values.query) {
          output({ status: "error", error: "--query is required for 'search' command" });
          return;
        }

        const query = encodeURIComponent(values.query);
        const response = await graphRequest<{ value: GraphEmail[] }>(
          token,
          `/me/messages?$search="${query}"&$top=${top}&$orderby=receivedDateTime desc`
        );

        output({
          status: "success",
          data: response.value.map((email) => ({
            id: email.id,
            subject: email.subject,
            from: email.from.emailAddress,
            receivedDateTime: email.receivedDateTime,
            bodyPreview: email.bodyPreview,
            isRead: email.isRead,
            hasAttachments: email.hasAttachments,
          })),
        });
        break;
      }

      case "folders": {
        const response = await graphRequest<{ value: MailFolder[] }>(
          token,
          `/me/mailFolders?$top=50`
        );

        output({
          status: "success",
          data: response.value.map((folder) => ({
            id: folder.id,
            displayName: folder.displayName,
            unreadItemCount: folder.unreadItemCount,
            totalItemCount: folder.totalItemCount,
            childFolderCount: folder.childFolderCount,
          })),
        });
        break;
      }

      case "send": {
        if (!values.to) {
          output({ status: "error", error: "--to is required for 'send' command" });
          return;
        }
        if (!values.subject) {
          output({ status: "error", error: "--subject is required for 'send' command" });
          return;
        }
        if (!values.body) {
          output({ status: "error", error: "--body is required for 'send' command" });
          return;
        }

        const message: {
          subject: string;
          body: { contentType: string; content: string };
          toRecipients: Array<{ emailAddress: { address: string } }>;
          ccRecipients?: Array<{ emailAddress: { address: string } }>;
          bccRecipients?: Array<{ emailAddress: { address: string } }>;
        } = {
          subject: values.subject,
          body: {
            contentType: values.html ? "HTML" : "Text",
            content: values.body,
          },
          toRecipients: parseRecipients(values.to),
        };

        if (values.cc) {
          message.ccRecipients = parseRecipients(values.cc);
        }
        if (values.bcc) {
          message.bccRecipients = parseRecipients(values.bcc);
        }

        await graphPost(token, "/me/sendMail", { message });

        output({
          status: "success",
          data: {
            sent: true,
            to: values.to,
            subject: values.subject,
          },
        });
        break;
      }

      default:
        output({ status: "error", error: `Unknown command: ${command}. Use --help for usage.` });
    }
  } catch (error) {
    output({
      status: "error",
      error: error instanceof Error ? error.message : "Unknown error",
    });
  }
}

main();

/**
 * Auth Handler - Reusable authentication wrapper
 *
 * Provides a simple interface for scripts to ensure authentication
 * before making API calls. Handles token refresh and device code flow.
 */

import {
  getCredential,
  setCredential,
  isTokenExpired,
} from "./credentials";
import {
  getPendingAuth,
  setPendingAuth,
  deletePendingAuth,
  isPendingExpired,
  type PendingAuth,
} from "./pending-auth";
import {
  requestDeviceCode,
  pollForToken,
  refreshAccessToken,
} from "./device-code";
import type { Credential } from "./types";

const DEFAULT_CLIENT_ID = "14d82eec-204b-4c2f-b7e8-296a70dab67e";
const DEFAULT_TENANT = "common";

export interface AuthHandlerOptions {
  service: string;
  profile: string;
  requiredScopes: string[];
  clientId?: string;
  tenantId?: string;
}

// Response types for scripts
export type ScriptResponse<T> =
  | { status: "success"; data: T }
  | {
      status: "auth_required";
      userCode: string;
      verificationUri: string;
      expiresAt: string;
      message: string;
    }
  | {
      status: "auth_pending";
      userCode: string;
      verificationUri: string;
      expiresAt: string;
      message: string;
    }
  | { status: "auth_expired"; message: string }
  | { status: "error"; error: string };

export type AuthResult<T> =
  | { ok: true; token: string }
  | { ok: false; response: ScriptResponse<T> };

/**
 * Ensure authentication is ready before making API calls.
 *
 * Usage:
 * ```typescript
 * const auth = await ensureAuth({
 *   service: "microsoft-graph",
 *   profile: "default",
 *   requiredScopes: ["Mail.Read"],
 * });
 *
 * if (!auth.ok) {
 *   console.log(JSON.stringify(auth.response));
 *   process.exit(1);
 * }
 *
 * // Use auth.token for API calls
 * ```
 */
export async function ensureAuth<T>(
  options: AuthHandlerOptions
): Promise<AuthResult<T>> {
  const {
    service,
    profile,
    requiredScopes,
    clientId = DEFAULT_CLIENT_ID,
    tenantId = DEFAULT_TENANT,
  } = options;

  // Step 1: Check for existing valid credential
  const credential = await getCredential(service, profile);

  if (credential) {
    // Step 2: Check if token is still valid (with 5 min buffer)
    if (!isTokenExpired(credential)) {
      return { ok: true, token: credential.accessToken };
    }

    // Token expired - try to refresh
    if (credential.refreshToken) {
      const refreshedToken = await refreshAccessToken(
        credential.clientId ?? clientId,
        credential.tenantId ?? tenantId,
        credential.refreshToken,
        requiredScopes
      );

      if (refreshedToken) {
        const expiresAt = new Date(
          Date.now() + refreshedToken.expiresIn * 1000
        ).toISOString();

        const newCredential: Credential = {
          accessToken: refreshedToken.accessToken,
          refreshToken: refreshedToken.refreshToken,
          expiresAt,
          account: credential.account,
          scopes: refreshedToken.scope?.split(" ") ?? credential.scopes,
          clientId: credential.clientId,
          tenantId: credential.tenantId,
        };

        await setCredential(service, profile, newCredential);
        return { ok: true, token: newCredential.accessToken };
      }
    }
  }

  // Step 3: Check for pending auth flow
  const pending = await getPendingAuth(service, profile);

  if (pending) {
    if (isPendingExpired(pending)) {
      // Pending auth expired - clean up and start fresh
      await deletePendingAuth(service, profile);
    } else {
      // Poll to see if user has completed authentication
      const pollResult = await pollForToken(
        pending.clientId,
        pending.tenantId,
        pending.deviceCode
      );

      if (pollResult.status === "success") {
        // User completed auth - save credential and return token
        const expiresAt = new Date(
          Date.now() + pollResult.token.expiresIn * 1000
        ).toISOString();

        // Extract account from token (basic JWT decode)
        let account = "unknown";
        try {
          const payload = JSON.parse(
            Buffer.from(
              pollResult.token.accessToken.split(".")[1],
              "base64"
            ).toString()
          );
          account =
            payload.preferred_username ||
            payload.upn ||
            payload.email ||
            "unknown";
        } catch {
          // Ignore decode errors
        }

        const newCredential: Credential = {
          accessToken: pollResult.token.accessToken,
          refreshToken: pollResult.token.refreshToken,
          expiresAt,
          account,
          scopes: pollResult.token.scope?.split(" ") ?? requiredScopes,
          clientId: pending.clientId,
          tenantId: pending.tenantId,
        };

        await setCredential(service, profile, newCredential);
        await deletePendingAuth(service, profile);
        return { ok: true, token: newCredential.accessToken };
      }

      if (pollResult.status === "pending") {
        // Still waiting for user
        return {
          ok: false,
          response: {
            status: "auth_pending",
            userCode: pending.userCode,
            verificationUri: pending.verificationUri,
            expiresAt: pending.expiresAt,
            message: `Authentication in progress. Go to ${pending.verificationUri} and enter code: ${pending.userCode}`,
          },
        };
      }

      if (pollResult.status === "expired") {
        // Device code expired - clean up
        await deletePendingAuth(service, profile);
      }

      // Error case - clean up and fall through to start new flow
      if (pollResult.status === "error") {
        await deletePendingAuth(service, profile);
      }
    }
  }

  // Step 4: Start new device code flow
  try {
    const deviceCode = await requestDeviceCode(clientId, tenantId, requiredScopes);

    const expiresAt = new Date(
      Date.now() + deviceCode.expiresIn * 1000
    ).toISOString();

    const newPending: PendingAuth = {
      deviceCode: deviceCode.deviceCode,
      userCode: deviceCode.userCode,
      verificationUri: deviceCode.verificationUri,
      expiresAt,
      clientId,
      tenantId,
      scopes: requiredScopes,
      profile,
    };

    await setPendingAuth(service, profile, newPending);

    return {
      ok: false,
      response: {
        status: "auth_required",
        userCode: deviceCode.userCode,
        verificationUri: deviceCode.verificationUri,
        expiresAt,
        message: deviceCode.message,
      },
    };
  } catch (error) {
    return {
      ok: false,
      response: {
        status: "error",
        error:
          error instanceof Error
            ? error.message
            : "Failed to start authentication",
      },
    };
  }
}

import { homedir } from "os";
import { join } from "path";
import { readFile, writeFile, mkdir } from "fs/promises";
import type { Credential, CredentialStore } from "./types";

const CONFIG_DIR = join(homedir(), ".config", "api-skills");
const CREDENTIALS_FILE = join(CONFIG_DIR, "credentials.json");

export async function ensureConfigDir(): Promise<void> {
  await mkdir(CONFIG_DIR, { recursive: true });
}

export async function loadCredentials(): Promise<CredentialStore> {
  try {
    const content = await readFile(CREDENTIALS_FILE, "utf-8");
    return JSON.parse(content);
  } catch {
    return {};
  }
}

export async function saveCredentials(store: CredentialStore): Promise<void> {
  await ensureConfigDir();
  await writeFile(CREDENTIALS_FILE, JSON.stringify(store, null, 2));
}

export async function getCredential(
  service: string,
  profile: string = "default"
): Promise<Credential | null> {
  const store = await loadCredentials();
  return store[service]?.[profile] ?? null;
}

export async function setCredential(
  service: string,
  profile: string,
  credential: Credential
): Promise<void> {
  const store = await loadCredentials();
  if (!store[service]) {
    store[service] = {};
  }
  store[service][profile] = credential;
  await saveCredentials(store);
}

export async function listProfiles(service: string): Promise<string[]> {
  const store = await loadCredentials();
  return Object.keys(store[service] ?? {});
}

export async function deleteCredential(
  service: string,
  profile: string
): Promise<boolean> {
  const store = await loadCredentials();
  if (store[service]?.[profile]) {
    delete store[service][profile];
    if (Object.keys(store[service]).length === 0) {
      delete store[service];
    }
    await saveCredentials(store);
    return true;
  }
  return false;
}

export function isTokenExpired(credential: Credential): boolean {
  const expiresAt = new Date(credential.expiresAt);
  const now = new Date();
  // Consider expired if less than 5 minutes remaining
  return expiresAt.getTime() - now.getTime() < 5 * 60 * 1000;
}

/**
 * Device Code Flow - Direct Azure HTTP API
 *
 * Handles device code OAuth flow without MSAL for non-blocking operation.
 * Uses direct HTTP requests to Azure AD endpoints.
 */

export interface DeviceCodeResponse {
  deviceCode: string;
  userCode: string;
  verificationUri: string;
  expiresIn: number;
  interval: number;
  message: string;
}

export interface TokenResponse {
  accessToken: string;
  refreshToken: string;
  expiresIn: number;
  scope: string;
}

export type PollResult =
  | { status: "success"; token: TokenResponse }
  | { status: "pending" }
  | { status: "expired" }
  | { status: "error"; error: string };

/**
 * Request a device code from Azure AD
 */
export async function requestDeviceCode(
  clientId: string,
  tenantId: string,
  scopes: string[]
): Promise<DeviceCodeResponse> {
  const url = `https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/devicecode`;

  const body = new URLSearchParams({
    client_id: clientId,
    scope: scopes.join(" "),
  });

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
    },
    body: body.toString(),
  });

  if (!response.ok) {
    const error = await response.text();
    throw new Error(`Device code request failed: ${response.status} - ${error}`);
  }

  const data = await response.json();

  return {
    deviceCode: data.device_code,
    userCode: data.user_code,
    verificationUri: data.verification_uri,
    expiresIn: data.expires_in,
    interval: data.interval || 5,
    message: data.message,
  };
}

/**
 * Poll Azure AD to check if user has completed authentication
 */
export async function pollForToken(
  clientId: string,
  tenantId: string,
  deviceCode: string
): Promise<PollResult> {
  const url = `https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/token`;

  const body = new URLSearchParams({
    client_id: clientId,
    grant_type: "urn:ietf:params:oauth:grant-type:device_code",
    device_code: deviceCode,
  });

  try {
    const response = await fetch(url, {
      method: "POST",
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
      },
      body: body.toString(),
    });

    const data = await response.json();

    if (response.ok) {
      return {
        status: "success",
        token: {
          accessToken: data.access_token,
          refreshToken: data.refresh_token,
          expiresIn: data.expires_in,
          scope: data.scope,
        },
      };
    }

    // Handle specific error codes
    const errorCode = data.error;

    if (errorCode === "authorization_pending") {
      return { status: "pending" };
    }

    if (errorCode === "expired_token") {
      return { status: "expired" };
    }

    // Other errors (authorization_declined, bad_verification_code, etc.)
    return {
      status: "error",
      error: data.error_description || data.error || "Unknown error",
    };
  } catch (error) {
    return {
      status: "error",
      error: error instanceof Error ? error.message : "Network error",
    };
  }
}

/**
 * Refresh an access token using a refresh token
 */
export async function refreshAccessToken(
  clientId: string,
  tenantId: string,
  refreshToken: string,
  scopes: string[]
): Promise<TokenResponse | null> {
  const url = `https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/token`;

  const body = new URLSearchParams({
    client_id: clientId,
    grant_type: "refresh_token",
    refresh_token: refreshToken,
    scope: scopes.join(" "),
  });

  try {
    const response = await fetch(url, {
      method: "POST",
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
      },
      body: body.toString(),
    });

    if (!response.ok) {
      return null;
    }

    const data = await response.json();

    return {
      accessToken: data.access_token,
      refreshToken: data.refresh_token || refreshToken,
      expiresIn: data.expires_in,
      scope: data.scope,
    };
  } catch {
    return null;
  }
}

import {
  PublicClientApplication,
  DeviceCodeRequest,
  AuthenticationResult,
} from "@azure/msal-node";
import {
  getCredential,
  setCredential,
  isTokenExpired,
} from "./credentials";
import type { Credential } from "./types";

// Microsoft Graph API scopes
export const GRAPH_SCOPES = {
  mail: ["Mail.Read", "Mail.ReadBasic"],
  mailSend: ["Mail.Send"],
  calendar: ["Calendars.Read"],
  calendarWrite: ["Calendars.ReadWrite"],
  user: ["User.Read"],
};

// Default client ID for device code flow (Microsoft Graph Explorer)
// Users should register their own app for production use
const DEFAULT_CLIENT_ID = "14d82eec-204b-4c2f-b7e8-296a70dab67e";
const DEFAULT_TENANT = "common";

export interface GraphClientOptions {
  profile?: string;
  clientId?: string;
  tenantId?: string;
}

export class GraphClient {
  private profile: string;
  private clientId: string;
  private tenantId: string;
  private pca: PublicClientApplication | null = null;

  constructor(options: GraphClientOptions = {}) {
    this.profile = options.profile ?? "default";
    this.clientId = options.clientId ?? DEFAULT_CLIENT_ID;
    this.tenantId = options.tenantId ?? DEFAULT_TENANT;
  }

  private async initPca(): Promise<PublicClientApplication> {
    if (this.pca) return this.pca;

    // Try to load clientId from stored credentials if using defaults
    if (this.clientId === DEFAULT_CLIENT_ID) {
      const credential = await getCredential("microsoft-graph", this.profile);
      if (credential?.clientId) {
        this.clientId = credential.clientId;
      }
      if (credential?.tenantId) {
        this.tenantId = credential.tenantId;
      }
    }

    this.pca = new PublicClientApplication({
      auth: {
        clientId: this.clientId,
        authority: `https://login.microsoftonline.com/${this.tenantId}`,
      },
    });

    return this.pca;
  }

  async getAccessToken(requiredScopes: string[]): Promise<string> {
    const credential = await getCredential("microsoft-graph", this.profile);

    if (credential && !isTokenExpired(credential)) {
      // Check if we have all required scopes
      const hasAllScopes = requiredScopes.every((scope) =>
        credential.scopes.some(
          (s) => s.toLowerCase() === scope.toLowerCase()
        )
      );
      if (hasAllScopes) {
        return credential.accessToken;
      }
    }

    // Try silent token acquisition with refresh token
    if (credential?.refreshToken) {
      try {
        const pca = await this.initPca();
        const result = await pca.acquireTokenByRefreshToken({
          refreshToken: credential.refreshToken,
          scopes: requiredScopes,
        });

        if (result) {
          await this.saveAuthResult(result, requiredScopes);
          return result.accessToken;
        }
      } catch {
        // Refresh failed, need interactive auth
      }
    }

    // Need interactive auth - throw error with instructions
    throw new Error(
      `No valid token for profile "${this.profile}". Run auth first:\n` +
        `bun run ${process.env.CLAUDE_PLUGIN_ROOT}/skills/microsoft-graph/scripts/auth.ts --profile ${this.profile}`
    );
  }

  async authenticate(scopes: string[]): Promise<AuthenticationResult> {
    const pca = await this.initPca();

    const deviceCodeRequest: DeviceCodeRequest = {
      scopes,
      deviceCodeCallback: (response) => {
        console.log("\n" + response.message);
        console.log("\nWaiting for authentication...\n");
      },
    };

    const result = await pca.acquireTokenByDeviceCode(deviceCodeRequest);
    if (!result) {
      throw new Error("Authentication failed: no result returned");
    }
    await this.saveAuthResult(result, scopes);
    return result;
  }

  private async saveAuthResult(
    result: AuthenticationResult,
    requestedScopes: string[]
  ): Promise<void> {
    // Get scopes from the result, or use requested scopes if not available
    const scopes = result.scopes?.length > 0 ? result.scopes : requestedScopes;

    const credential: Credential = {
      accessToken: result.accessToken,
      refreshToken: (result as any).refreshToken ?? "",
      expiresAt: result.expiresOn?.toISOString() ?? new Date(Date.now() + 3600000).toISOString(),
      account: result.account?.username ?? "unknown",
      scopes,
      clientId: this.clientId !== DEFAULT_CLIENT_ID ? this.clientId : undefined,
      tenantId: this.tenantId !== DEFAULT_TENANT ? this.tenantId : undefined,
    };

    await setCredential("microsoft-graph", this.profile, credential);
  }

  async graphRequest<T>(
    endpoint: string,
    scopes: string[],
    options: RequestInit = {}
  ): Promise<T> {
    const token = await this.getAccessToken(scopes);

    const response = await fetch(`https://graph.microsoft.com/v1.0${endpoint}`, {
      ...options,
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
        ...options.headers,
      },
    });

    if (!response.ok) {
      const error = await response.text();
      throw new Error(`Graph API error (${response.status}): ${error}`);
    }

    return response.json();
  }

  getClientId(): string {
    return this.clientId;
  }

  getTenantId(): string {
    return this.tenantId;
  }
}

/**
 * Pending Auth State Management
 *
 * Stores in-progress device code flow state on disk so authentication
 * can be resumed without conversation context.
 */

import { homedir } from "os";
import { join } from "path";
import { mkdir, readFile, writeFile, unlink } from "fs/promises";

export interface PendingAuth {
  deviceCode: string;
  userCode: string;
  verificationUri: string;
  expiresAt: string;
  clientId: string;
  tenantId: string;
  scopes: string[];
  profile: string;
}

interface PendingAuthStore {
  [service: string]: {
    [profile: string]: PendingAuth;
  };
}

const PENDING_AUTH_PATH = join(
  homedir(),
  ".config",
  "api-skills",
  "pending-auth.json"
);

async function ensureDir(): Promise<void> {
  const dir = join(homedir(), ".config", "api-skills");
  await mkdir(dir, { recursive: true });
}

async function loadStore(): Promise<PendingAuthStore> {
  try {
    const data = await readFile(PENDING_AUTH_PATH, "utf-8");
    const parsed = JSON.parse(data);
    return typeof parsed === "object" && parsed !== null ? parsed : {};
  } catch {
    return {};
  }
}

async function saveStore(store: PendingAuthStore): Promise<void> {
  await ensureDir();
  await writeFile(PENDING_AUTH_PATH, JSON.stringify(store, null, 2));
}

export async function getPendingAuth(
  service: string,
  profile: string
): Promise<PendingAuth | null> {
  const store = await loadStore();
  return store[service]?.[profile] ?? null;
}

export async function setPendingAuth(
  service: string,
  profile: string,
  pending: PendingAuth
): Promise<void> {
  const store = await loadStore();
  if (!store[service]) {
    store[service] = {};
  }
  store[service][profile] = pending;
  await saveStore(store);
}

export async function deletePendingAuth(
  service: string,
  profile: string
): Promise<void> {
  const store = await loadStore();
  if (store[service]?.[profile]) {
    delete store[service][profile];
    if (Object.keys(store[service]).length === 0) {
      delete store[service];
    }
    await saveStore(store);
  }
}

export function isPendingExpired(pending: PendingAuth): boolean {
  const expiresAt = new Date(pending.expiresAt);
  return expiresAt.getTime() <= Date.now();
}

export interface Credential {
  accessToken: string;
  refreshToken: string;
  expiresAt: string;
  account: string;
  scopes: string[];
  clientId?: string;
  tenantId?: string;
}

export interface CredentialStore {
  [service: string]: {
    [profileName: string]: Credential;
  };
}

export interface GraphEmail {
  id: string;
  subject: string;
  from: {
    emailAddress: {
      name: string;
      address: string;
    };
  };
  receivedDateTime: string;
  bodyPreview: string;
  body?: {
    contentType: string;
    content: string;
  };
  isRead: boolean;
  hasAttachments: boolean;
}

export interface GraphCalendarEvent {
  id: string;
  subject: string;
  start: {
    dateTime: string;
    timeZone: string;
  };
  end: {
    dateTime: string;
    timeZone: string;
  };
  location?: {
    displayName: string;
  };
  organizer?: {
    emailAddress: {
      name: string;
      address: string;
    };
  };
  attendees?: Array<{
    emailAddress: {
      name: string;
      address: string;
    };
    status?: {
      response: string;
    };
  }>;
  bodyPreview?: string;
  isAllDay?: boolean;
}

export interface MailFolder {
  id: string;
  displayName: string;
  parentFolderId?: string;
  childFolderCount: number;
  unreadItemCount: number;
  totalItemCount: number;
}

{
  "schema_version": "2.0",
  "meta": {
    "generated_at": "2026-01-16T19:02:39.054Z",
    "slug": "bltgv-microsoft-graph-api",
    "source_url": "https://github.com/BLTGV/agent-skills/tree/master/skills/microsoft-graph",
    "source_ref": "master",
    "model": "claude",
    "analysis_version": "3.0.0",
    "source_type": "community",
    "content_hash": "ab89f22136609b892b733c680f5d4d292cc2ee53383038afe06fb8f715335c03",
    "tree_hash": "24e31f60471f53215bf980a65052984588ad86623a0049342f1e70c2686e9fa3"
  },
  "skill": {
    "name": "microsoft-graph-api",
    "description": "This skill should be used when the user asks to \"read my emails\", \"send an email\", \"compose email\", \"check my calendar\", \"get calendar events\", \"create a meeting\", \"schedule an event\", \"add calendar event\", \"search emails\", \"list mail folders\", \"show unread messages\", \"what meetings do I have\", \"fetch emails from Microsoft\", \"access Outlook\", or mentions Microsoft Graph, Office 365 email, or Outlook calendar integration.",
    "summary": "This skill should be used when the user asks to \"read my emails\", \"send an email\", \"compose email\", ...",
    "icon": "📧",
    "version": "0.3.0",
    "author": "BLTGV",
    "license": "MIT",
    "category": "office",
    "tags": [
      "microsoft",
      "email",
      "calendar",
      "office-365",
      "productivity"
    ],
    "supported_tools": [
      "claude",
      "codex",
      "claude-code"
    ],
    "risk_factors": [
      "external_commands",
      "network",
      "filesystem"
    ]
  },
  "security_audit": {
    "risk_level": "low",
    "is_blocked": false,
    "safe_to_publish": true,
    "summary": "The static analyzer flagged 317 issues, but upon evaluation, ALL findings are FALSE POSITIVES. The code is a legitimate Microsoft Graph API integration using standard OAuth 2.0 device code flow. The 'backtick execution' detections are template literals in documentation and code, not shell commands. 'Hardcoded URL' findings are public Microsoft API endpoints, not secrets. 'C2 keywords' are the official Microsoft Graph Explorer client ID. All credential handling follows standard OAuth patterns with the @azure/msal-node library.",
    "risk_factor_evidence": [
      {
        "factor": "external_commands",
        "evidence": [
          {
            "file": "SKILL.md",
            "line_start": 74,
            "line_end": 210
          },
          {
            "file": "scripts/auth.ts",
            "line_start": 56,
            "line_end": 210
          },
          {
            "file": "scripts/emails.ts",
            "line_start": 65,
            "line_end": 349
          },
          {
            "file": "scripts/calendar.ts",
            "line_start": 66,
            "line_end": 420
          }
        ]
      },
      {
        "factor": "network",
        "evidence": [
          {
            "file": "scripts/lib/graph-client.ts",
            "line_start": 155,
            "line_end": 155
          },
          {
            "file": "scripts/lib/device-code.ts",
            "line_start": 38,
            "line_end": 175
          }
        ]
      },
      {
        "factor": "filesystem",
        "evidence": [
          {
            "file": "scripts/lib/credentials.ts",
            "line_start": 6,
            "line_end": 7
          },
          {
            "file": "scripts/lib/pending-auth.ts",
            "line_start": 29,
            "line_end": 34
          }
        ]
      }
    ],
    "critical_findings": [],
    "high_findings": [],
    "medium_findings": [],
    "low_findings": [],
    "dangerous_patterns": [],
    "files_scanned": 12,
    "total_lines": 2677,
    "audit_model": "claude",
    "audited_at": "2026-01-16T19:02:39.054Z"
  },
  "content": {
    "user_title": "Access Microsoft 365 email and calendar",
    "value_statement": "Users need to read and manage their Microsoft 365 emails and calendar events without leaving their AI assistant. This skill provides direct integration with Microsoft Graph API to list, read, search, and send emails as well as view and create calendar events using OAuth authentication.",
    "seo_keywords": [
      "Microsoft Graph API",
      "Office 365 email",
      "Outlook calendar",
      "Microsoft 365 integration",
      "email automation",
      "calendar management",
      "Claude",
      "Codex",
      "Claude Code"
    ],
    "actual_capabilities": [
      "List, read, search, and send emails via Microsoft Graph API",
      "View, search, and create calendar events and meetings",
      "Manage multiple credential profiles for different accounts",
      "Handle OAuth device code flow authentication automatically",
      "List mail folders and filter emails by sender, subject, or date",
      "Create calendar events with attendees, locations, and all-day support"
    ],
    "limitations": [
      "Requires Microsoft account with appropriate Graph API permissions",
      "Access tokens expire after approximately 90 days of inactivity",
      "Cannot access shared mailboxes or delegation without separate setup",
      "Rate limited by Microsoft Graph API quotas"
    ],
    "use_cases": [
      {
        "target_user": "Remote workers",
        "title": "Check email and schedule",
        "description": "Quickly check inbox for important emails and view today's calendar meetings"
      },
      {
        "target_user": "Administrative assistants",
        "title": "Schedule meetings",
        "description": "Create calendar events and send meeting invitations to attendees"
      },
      {
        "target_user": "Project managers",
        "title": "Find communications",
        "description": "Search email threads and calendar events for project-related discussions"
      }
    ],
    "prompt_templates": [
      {
        "title": "List recent emails",
        "scenario": "Read inbox messages",
        "prompt": "List my recent emails from the inbox"
      },
      {
        "title": "Check calendar",
        "scenario": "View today's schedule",
        "prompt": "What meetings do I have today"
      },
      {
        "title": "Send email",
        "scenario": "Compose and send message",
        "prompt": "Send an email to team@example.com about the project update"
      },
      {
        "title": "Create meeting",
        "scenario": "Schedule event",
        "prompt": "Create a team meeting for tomorrow at 2pm with john@example.com and jane@example.com"
      }
    ],
    "output_examples": [
      {
        "input": "List my recent emails",
        "output": [
          "Recent emails from inbox:",
          "- Subject: Project Update, From: john@company.com, 10:30 AM",
          "- Subject: Meeting Tomorrow, From: jane@company.com, 9:15 AM",
          "- Subject: Newsletter, From: team@newsletter.com, Yesterday"
        ]
      },
      {
        "input": "What meetings do I have today",
        "output": [
          "Today's calendar:",
          "- 10:00 AM: Team Standup (1 hour) - Conference Room A",
          "- 2:00 PM: Project Review (30 min) - Video Call"
        ]
      },
      {
        "input": "Send an email about the project update",
        "output": [
          "Email sent successfully:",
          "To: team@example.com",
          "Subject: Project Update",
          "The email has been delivered."
        ]
      }
    ],
    "best_practices": [
      "Use specific profiles when managing multiple Microsoft accounts to keep credentials separate",
      "Run the auth.ts script first to complete device code authentication before using email or calendar features",
      "Request only the necessary scopes (Mail.Read, Calendars.Read) rather than full access when possible"
    ],
    "anti_patterns": [
      "Using the same profile for personal and work accounts - create separate profiles instead",
      "Sharing credential files between users - each user should authenticate their own account",
      "Ignoring auth_required responses - always complete the device code flow when prompted"
    ],
    "faq": [
      {
        "question": "How do I authenticate for the first time?",
        "answer": "Run any email or calendar command. If not authenticated, the skill returns auth_required with a code. Open the displayed URL, enter the code, and sign in with Microsoft."
      },
      {
        "question": "How long do tokens remain valid?",
        "answer": "Access tokens expire after 1 hour but refresh automatically. Refresh tokens last approximately 90 days before requiring re-authentication."
      },
      {
        "question": "Can I use this with my work Microsoft account?",
        "answer": "Yes, the skill works with both work and personal Microsoft accounts. Use --profile to manage different accounts separately."
      },
      {
        "question": "Where are credentials stored?",
        "answer": "OAuth tokens are stored in ~/.config/api-skills/credentials.json with standard file permissions."
      },
      {
        "question": "What permissions does the app require?",
        "answer": "By default, it requests Mail.Read, Mail.Send, Calendars.Read, Calendars.ReadWrite, and User.Read scopes for full functionality."
      },
      {
        "question": "Can I use my own Azure AD app registration?",
        "answer": "Yes, run auth.ts with --client-id and --tenant-id options to use a custom app registration for production use."
      }
    ]
  },
  "file_structure": [
    {
      "name": "references",
      "type": "dir",
      "path": "references",
      "children": [
        {
          "name": "graph-api.md",
          "type": "file",
          "path": "references/graph-api.md",
          "lines": 306
        }
      ]
    },
    {
      "name": "scripts",
      "type": "dir",
      "path": "scripts",
      "children": [
        {
          "name": "lib",
          "type": "dir",
          "path": "scripts/lib",
          "children": [
            {
              "name": "auth-handler.ts",
              "type": "file",
              "path": "scripts/lib/auth-handler.ts",
              "lines": 255
            },
            {
              "name": "credentials.ts",
              "type": "file",
              "path": "scripts/lib/credentials.ts",
              "lines": 75
            },
            {
              "name": "device-code.ts",
              "type": "file",
              "path": "scripts/lib/device-code.ts",
              "lines": 176
            },
            {
              "name": "graph-client.ts",
              "type": "file",
              "path": "scripts/lib/graph-client.ts",
              "lines": 180
            },
            {
              "name": "pending-auth.ts",
              "type": "file",
              "path": "scripts/lib/pending-auth.ts",
              "lines": 95
            },
            {
              "name": "types.ts",
              "type": "file",
              "path": "scripts/lib/types.ts",
              "lines": 77
            }
          ]
        },
        {
          "name": "auth.ts",
          "type": "file",
          "path": "scripts/auth.ts",
          "lines": 210
        },
        {
          "name": "calendar.ts",
          "type": "file",
          "path": "scripts/calendar.ts",
          "lines": 421
        },
        {
          "name": "emails.ts",
          "type": "file",
          "path": "scripts/emails.ts",
          "lines": 350
        }
      ]
    },
    {
      "name": "SKILL.md",
      "type": "file",
      "path": "SKILL.md",
      "lines": 224
    }
  ]
}