m365-agent-cli 1.2.0

package/src/commands/find.ts

@@ -0,0 +1,195 @@
+import { Command } from 'commander';
+import { resolveGraphAuth } from '../lib/graph-auth.js';
+import { expandGroup, searchGroups, searchPeople, searchUsers } from '../lib/graph-directory.js';
+
+export const findCommand = new Command('find')
+  .description('Search for people or groups in the directory')
+  .argument('<query>', 'Search query (name, email, etc.)')
+  .option('--people', 'Only search people/users')
+  .option('--groups', 'Only search groups')
+  .option('--expand', 'Expand group members if the query matches a group')
+  .option('--json', 'Output as JSON')
+  .option('--token <token>', 'Use a specific token')
+  .option('--identity <name>', 'Graph token cache identity (default: default)')
+  .action(
+    async (
+      query: string,
+      options: {
+        people?: boolean;
+        groups?: boolean;
+        expand?: boolean;
+        json?: boolean;
+        token?: string;
+        identity?: string;
+      }
+    ) => {
+      const authResult = await resolveGraphAuth({
+        token: options.token,
+        identity: options.identity
+      });
+
+      if (!authResult.success) {
+        if (options.json) {
+          console.log(JSON.stringify({ error: authResult.error }, null, 2));
+        } else {
+          console.error(`Error: ${authResult.error}`);
+          console.error('\nCheck your .env file or run m365-agent-cli auth.');
+        }
+        process.exit(1);
+      }
+
+      const token = authResult.token!;
+      try {
+        const results: any[] = [];
+        const errors: string[] = [];
+
+        const searchAll = !options.people && !options.groups;
+
+        if (searchAll || options.people) {
+          const peopleRes = await searchPeople(token, query);
+          if (peopleRes.ok && peopleRes.data) {
+            results.push(
+              ...peopleRes.data.map((p) => ({
+                id: p.id,
+                type: 'Person',
+                name: p.displayName,
+                email: p.userPrincipalName || p.scoredEmailAddresses?.[0]?.address,
+                title: p.jobTitle,
+                department: p.department,
+                userPrincipalName: p.userPrincipalName
+              }))
+            );
+          } else if (peopleRes.error) {
+            if (peopleRes.error.status === 403) {
+              // Default auth scopes may not cover People API - suppress 403 unless --people was explicitly requested
+              if (options.people) {
+                errors.push(`People search failed: ${peopleRes.error.message}`);
+              }
+            } else {
+              errors.push(`People search failed: ${peopleRes.error.message}`);
+            }
+          }
+
+          const usersRes = await searchUsers(token, query);
+          if (usersRes.ok && usersRes.data) {
+            for (const u of usersRes.data) {
+              const userEmail = u.mail || u.userPrincipalName;
+              const userUpn = u.userPrincipalName;
+              if (
+                !results.find(
+                  (r) =>
+                    (r.userPrincipalName && userUpn && r.userPrincipalName.toLowerCase() === userUpn.toLowerCase()) ||
+                    (r.email && userEmail && r.email.toLowerCase() === userEmail.toLowerCase())
+                )
+              ) {
+                results.push({
+                  id: u.id,
+                  type: 'Person',
+                  name: u.displayName,
+                  email: userEmail,
+                  title: u.jobTitle,
+                  department: u.department,
+                  userPrincipalName: u.userPrincipalName
+                });
+              }
+            }
+          } else if (usersRes.error) {
+            if (usersRes.error.status === 403) {
+              // Default auth scopes may not cover Users API - suppress 403 unless --people was explicitly requested
+              if (options.people) {
+                errors.push(`Users search failed: ${usersRes.error.message}`);
+              }
+            } else {
+              errors.push(`Users search failed: ${usersRes.error.message}`);
+            }
+          }
+        }
+
+        if (searchAll || options.groups) {
+          const groupsRes = await searchGroups(token, query);
+          if (groupsRes.ok && groupsRes.data) {
+            // Only expand members of the first group to avoid N+1 API calls
+            const groupsToExpand = options.expand ? groupsRes.data.slice(0, 1) : [];
+            for (const g of groupsRes.data) {
+              const groupItem: any = {
+                id: g.id,
+                type: 'Group',
+                name: g.displayName,
+                email: g.mail,
+                description: g.description
+              };
+
+              if (groupsToExpand.some((ge) => ge.id === g.id)) {
+                const membersRes = await expandGroup(token, g.id);
+                if (membersRes.ok && membersRes.data) {
+                  groupItem.members = membersRes.data.map((m: any) => ({
+                    id: m.id,
+                    name: m.displayName,
+                    email: m.mail || m.userPrincipalName
+                  }));
+                }
+              }
+              results.push(groupItem);
+            }
+          } else if (groupsRes.error) {
+            if (groupsRes.error.status === 403) {
+              // Default auth scopes may not cover Groups API - suppress 403 unless --groups was explicitly requested
+              if (options.groups) {
+                errors.push(`Groups search failed: ${groupsRes.error.message}`);
+              }
+            } else {
+              errors.push(`Groups search failed: ${groupsRes.error.message}`);
+            }
+          }
+        }
+
+        if (options.json) {
+          const output: any = { results };
+          if (errors.length > 0) output.errors = errors;
+          console.log(JSON.stringify(output, null, 2));
+          return;
+        }
+
+        if (errors.length > 0) {
+          console.error(`Warnings:`);
+          for (const e of errors) console.error(` - ${e}`);
+        }
+
+        if (results.length === 0) {
+          console.log(`\nNo results found for "${query}"\n`);
+          return;
+        }
+
+        console.log(`\nSearch results for "${query}":\n`);
+        console.log('\u2500'.repeat(80));
+
+        for (const res of results) {
+          const isGroup = res.type === 'Group';
+          const icon = isGroup ? '\u{1F465}' : '\u{1F464}';
+
+          console.log(`\n  ${icon} ${res.name} [${res.type}]`);
+          if (res.email) console.log(`     Email: ${res.email}`);
+          if (res.title) console.log(`     Title: ${res.title}`);
+          if (res.department) console.log(`     Dept:  ${res.department}`);
+          if (res.description) console.log(`     Desc:  ${res.description}`);
+
+          if (isGroup && res.members) {
+            console.log(`     Members (${res.members.length}):`);
+            for (const member of res.members) {
+              console.log(`       - ${member.name} ${member.email ? `(${member.email})` : ''}`);
+            }
+          }
+        }
+
+        console.log(`\n${'\u2500'.repeat(80)}\n`);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : 'Unknown error';
+        if (options.json) {
+          console.log(JSON.stringify({ error: message }, null, 2));
+        } else {
+          console.error(`Error: ${message}`);
+        }
+        process.exit(1);
+      }
+    }
+  );

package/src/commands/findtime.ts

@@ -0,0 +1,270 @@
+import { Command } from 'commander';
+import { resolveAuth } from '../lib/auth.js';
+import { parseDay } from '../lib/dates.js';
+import { getOwaUserInfo, getScheduleViaOutlook } from '../lib/ews-client.js';
+
+function formatTime(dateStr: string): string {
+  const date = new Date(dateStr);
+  return date.toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit', hour12: false });
+}
+
+function formatDate(dateStr: string): string {
+  const date = new Date(dateStr);
+  return date.toLocaleDateString('en-US', { weekday: 'short', month: 'short', day: 'numeric' });
+}
+
+function _formatDateTime(dateStr: string): string {
+  const _date = new Date(dateStr);
+  return `${formatDate(dateStr)} ${formatTime(dateStr)}`;
+}
+
+function isValidEmail(value: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+}
+
+function getDateRange(startDay: string, endDay?: string): { start: Date; end: Date; label: string } {
+  const now = new Date();
+
+  switch (startDay.toLowerCase()) {
+    case 'week':
+    case 'thisweek': {
+      const start = new Date(now);
+      const dayOfWeek = start.getDay();
+      start.setDate(start.getDate() + (dayOfWeek === 0 ? 1 : 8 - dayOfWeek));
+      start.setHours(0, 0, 0, 0);
+      const end = new Date(start);
+      end.setDate(end.getDate() + 4);
+      end.setHours(23, 59, 59, 999);
+      return { start, end, label: 'This Week (Mon-Fri)' };
+    }
+    case 'nextweek': {
+      const start = new Date(now);
+      const dayOfWeek = start.getDay();
+      const daysUntilNextMonday = dayOfWeek === 0 ? 1 : 8 - dayOfWeek;
+      start.setDate(start.getDate() + daysUntilNextMonday);
+      start.setHours(0, 0, 0, 0);
+      const end = new Date(start);
+      end.setDate(end.getDate() + 4);
+      end.setHours(23, 59, 59, 999);
+      return { start, end, label: 'Next Week (Mon-Fri)' };
+    }
+  }
+
+  const startDate = parseDay(startDay, { throwOnInvalid: true });
+  startDate.setHours(0, 0, 0, 0);
+
+  if (endDay) {
+    const endDate = parseDay(endDay, { baseDate: startDate, weekdayDirection: 'next', throwOnInvalid: true });
+    endDate.setHours(23, 59, 59, 999);
+    return {
+      start: startDate,
+      end: endDate,
+      label: `${formatDate(startDate.toISOString())} - ${formatDate(endDate.toISOString())}`
+    };
+  }
+
+  const endDate = new Date(startDate);
+  endDate.setHours(23, 59, 59, 999);
+  return { start: startDate, end: endDate, label: formatDate(startDate.toISOString()) };
+}
+
+export const findtimeCommand = new Command('findtime')
+  .description('Find available meeting times with one or more people')
+  .argument('[start]', 'Start: today, tomorrow, monday-sunday, week, nextweek, or YYYY-MM-DD', 'nextweek')
+  .argument('[endOrEmails...]', 'End day for range AND/OR email addresses')
+  .option('--duration <minutes>', 'Meeting duration in minutes', '30')
+  .option('--start <hour>', 'Work day start hour (0-23)', '9')
+  .option('--end <hour>', 'Work day end hour (0-23)', '17')
+  .option('--solo', "Only check specified people, don't include yourself")
+  .option('--json', 'Output as JSON')
+  .option('--token <token>', 'Use a specific token')
+  .option('--identity <name>', 'Use a specific authentication identity (default: default)')
+  .option('--mailbox <email>', 'EWS anchor mailbox (delegated / shared mailbox context)')
+  .action(
+    async (
+      startDay: string,
+      endOrEmails: string[],
+      options: {
+        duration: string;
+        start: string;
+        end: string;
+        solo?: boolean;
+        json?: boolean;
+        token?: string;
+        identity?: string;
+        mailbox?: string;
+      },
+      _cmd: any
+    ) => {
+      const authResult = await resolveAuth({
+        token: options.token,
+        identity: options.identity
+      });
+
+      if (!authResult.success) {
+        if (options.json) {
+          console.log(JSON.stringify({ error: authResult.error }, null, 2));
+        } else {
+          console.error(`Error: ${authResult.error}`);
+          console.error('\nCheck your .env file for EWS_CLIENT_ID and EWS_REFRESH_TOKEN.');
+        }
+        process.exit(1);
+      }
+
+      // Parse arguments: figure out which are dates vs emails
+      const dateKeywords = [
+        'today',
+        'tomorrow',
+        'monday',
+        'tuesday',
+        'wednesday',
+        'thursday',
+        'friday',
+        'saturday',
+        'sunday',
+        'week',
+        'thisweek',
+        'nextweek'
+      ];
+      const isDateArg = (arg: string) => {
+        if (dateKeywords.includes(arg.toLowerCase())) return true;
+        if (/^\d{4}-\d{2}-\d{2}$/.test(arg)) return true;
+        return false;
+      };
+
+      let endDay: string | undefined;
+      const emails: string[] = [];
+
+      for (const arg of endOrEmails) {
+        if (isDateArg(arg) && !endDay) {
+          endDay = arg;
+          continue;
+        }
+
+        if (!isValidEmail(arg)) {
+          console.error(`Error: Invalid attendee email: ${arg}`);
+          console.error('All attendee arguments must be valid email addresses.');
+          process.exit(1);
+        }
+
+        emails.push(arg);
+      }
+
+      // Get current user's email to include in search (unless --solo)
+      if (!options.solo) {
+        const userInfo = await getOwaUserInfo(authResult.token!);
+        if (!userInfo.ok || !userInfo.data?.email) {
+          if (options.json) {
+            console.log(JSON.stringify({ error: 'Failed to determine user email' }, null, 2));
+          } else {
+            console.error('Error: Failed to determine user email');
+          }
+          process.exit(1);
+        }
+        // Add current user if not already in the list
+        if (!emails.includes(userInfo.data.email)) {
+          emails.unshift(userInfo.data.email);
+        }
+      }
+
+      if (emails.length === 0) {
+        console.error('Error: Please provide at least one email address.');
+        console.error('\nUsage: m365-agent-cli findtime nextweek user@example.com');
+        process.exit(1);
+      }
+
+      let start: Date;
+      let end: Date;
+      let label: string;
+
+      try {
+        ({ start, end, label } = getDateRange(startDay, endDay));
+      } catch (err) {
+        const message = err instanceof Error ? err.message : 'Invalid date value';
+        if (options.json) {
+          console.log(JSON.stringify({ error: message }, null, 2));
+        } else {
+          console.error(`Error: ${message}`);
+        }
+        process.exit(1);
+      }
+      const duration = parseInt(options.duration, 10);
+
+      const result = await getScheduleViaOutlook(
+        authResult.token!,
+        emails,
+        start.toISOString(),
+        end.toISOString(),
+        duration,
+        undefined,
+        options.mailbox
+      );
+
+      if (!result.ok || !result.data) {
+        if (options.json) {
+          console.log(JSON.stringify({ error: result.error?.message || 'Failed to find meeting times' }, null, 2));
+        } else {
+          console.error(`Error: ${result.error?.message || 'Failed to find meeting times'}`);
+        }
+        process.exit(1);
+      }
+
+      // Extract free slots from the response, filtered to working hours
+      const workStart = parseInt(options.start, 10);
+      const workEnd = parseInt(options.end, 10);
+
+      const freeSlots = (result.data[0]?.scheduleItems || []).filter((item) => {
+        if (item.status !== 'Free') return false;
+        const hour = new Date(item.start.dateTime).getHours();
+        return hour >= workStart && hour < workEnd;
+      });
+
+      if (options.json) {
+        console.log(
+          JSON.stringify(
+            {
+              attendees: emails,
+              duration: duration,
+              dateRange: { start: start.toISOString(), end: end.toISOString() },
+              availableSlots: freeSlots.map((s) => ({
+                start: s.start.dateTime,
+                end: s.end.dateTime
+              }))
+            },
+            null,
+            2
+          )
+        );
+        return;
+      }
+
+      console.log(`\n🗓️  Finding ${duration}-minute meeting times`);
+      console.log(`   Attendees: ${emails.join(', ')}`);
+      console.log(`   Date range: ${label}`);
+      console.log('─'.repeat(50));
+
+      if (freeSlots.length === 0) {
+        console.log('\n  ❌ No available times found for all attendees.');
+        console.log('     Try a longer date range or shorter meeting duration.');
+      } else {
+        console.log(`\n  ✅ Found ${freeSlots.length} available slot${freeSlots.length > 1 ? 's' : ''}:\n`);
+
+        // Group by day
+        const byDay = new Map<string, typeof freeSlots>();
+        for (const slot of freeSlots) {
+          const day = slot.start.dateTime.split('T')[0];
+          if (!byDay.has(day)) byDay.set(day, []);
+          byDay.get(day)?.push(slot);
+        }
+
+        for (const [day, slots] of byDay) {
+          const dayLabel = formatDate(new Date(day).toISOString());
+          console.log(`  ${dayLabel}:`);
+          for (const slot of slots) {
+            console.log(`    🟢 ${formatTime(slot.start.dateTime)} - ${formatTime(slot.end.dateTime)}`);
+          }
+        }
+      }
+      console.log();
+    }
+  );

package/src/commands/folders.ts

@@ -0,0 +1,177 @@
+import { Command } from 'commander';
+import { resolveAuth } from '../lib/auth.js';
+import { createMailFolder, deleteMailFolder, getMailFolders, updateMailFolder } from '../lib/ews-client.js';
+import { checkReadOnly } from '../lib/utils.js';
+
+export const foldersCommand = new Command('folders')
+  .description('Manage mail folders')
+  .option('--create <name>', 'Create a new folder')
+  .option('--rename <name>', 'Rename a folder (use with --to)')
+  .option('--delete <name>', 'Delete a folder')
+  .option('--to <newname>', 'New name for rename operation')
+  .option('--json', 'Output as JSON')
+  .option('--token <token>', 'Use a specific token')
+  .option('--identity <name>', 'Use a specific authentication identity (default: default)')
+  .option('--mailbox <email>', 'Delegated or shared mailbox')
+  .action(
+    async (
+      options: {
+        create?: string;
+        rename?: string;
+        delete?: string;
+        to?: string;
+        json?: boolean;
+        token?: string;
+        identity?: string;
+        mailbox?: string;
+      },
+      cmd: any
+    ) => {
+      const authResult = await resolveAuth({
+        token: options.token,
+        identity: options.identity
+      });
+
+      if (!authResult.success) {
+        if (options.json) {
+          console.log(JSON.stringify({ error: authResult.error }, null, 2));
+        } else {
+          console.error(`Error: ${authResult.error}`);
+          console.error('\nCheck your .env file for EWS_CLIENT_ID and EWS_REFRESH_TOKEN.');
+        }
+        process.exit(1);
+      }
+
+      // Get all folders first (needed for most operations)
+      const foldersResult = await getMailFolders(authResult.token!, undefined, options.mailbox);
+      if (!foldersResult.ok || !foldersResult.data) {
+        console.error(`Error: ${foldersResult.error?.message || 'Failed to fetch folders'}`);
+        process.exit(1);
+      }
+
+      const folders = foldersResult.data.value;
+
+      // Helper to find folder by name (case-insensitive)
+      const findFolder = (name: string) => {
+        return folders.find((f) => f.DisplayName.toLowerCase() === name.toLowerCase());
+      };
+
+      // Handle create
+      if (options.create) {
+        checkReadOnly(cmd);
+        const existing = findFolder(options.create);
+        if (existing) {
+          console.error(`Folder "${options.create}" already exists.`);
+          process.exit(1);
+        }
+
+        const result = await createMailFolder(authResult.token!, options.create, undefined, options.mailbox);
+        if (!result.ok || !result.data) {
+          console.error(`Error: ${result.error?.message || 'Failed to create folder'}`);
+          process.exit(1);
+        }
+
+        if (options.json) {
+          console.log(JSON.stringify({ success: true, folder: result.data }, null, 2));
+        } else {
+          console.log(`\u2713 Created folder: ${result.data.DisplayName}`);
+        }
+        return;
+      }
+
+      // Handle rename
+      if (options.rename) {
+        checkReadOnly(cmd);
+        if (!options.to) {
+          console.error('Please specify new name with --to');
+          console.error('Example: m365-agent-cli folders --rename "Old Name" --to "New Name"');
+          process.exit(1);
+        }
+
+        const folder = findFolder(options.rename);
+        if (!folder) {
+          console.error(`Folder "${options.rename}" not found.`);
+          process.exit(1);
+        }
+
+        const result = await updateMailFolder(authResult.token!, folder.Id, options.to, options.mailbox);
+        if (!result.ok || !result.data) {
+          console.error(`Error: ${result.error?.message || 'Failed to rename folder'}`);
+          process.exit(1);
+        }
+
+        if (options.json) {
+          console.log(JSON.stringify({ success: true, folder: result.data }, null, 2));
+        } else {
+          console.log(`\u2713 Renamed "${options.rename}" to "${result.data.DisplayName}"`);
+        }
+        return;
+      }
+
+      // Handle delete
+      if (options.delete) {
+        checkReadOnly(cmd);
+        const folder = findFolder(options.delete);
+        if (!folder) {
+          console.error(`Folder "${options.delete}" not found.`);
+          process.exit(1);
+        }
+
+        // Prevent deleting system folders
+        const systemFolders = ['inbox', 'drafts', 'sent items', 'deleted items', 'junk email', 'archive', 'outbox'];
+        if (systemFolders.includes(folder.DisplayName.toLowerCase())) {
+          console.error(`Cannot delete system folder "${folder.DisplayName}".`);
+          process.exit(1);
+        }
+
+        const result = await deleteMailFolder(authResult.token!, folder.Id, options.mailbox);
+        if (!result.ok) {
+          console.error(`Error: ${result.error?.message || 'Failed to delete folder'}`);
+          process.exit(1);
+        }
+
+        if (options.json) {
+          console.log(JSON.stringify({ success: true, deleted: options.delete }, null, 2));
+        } else {
+          console.log(`\u2713 Deleted folder: ${options.delete}`);
+        }
+        return;
+      }
+
+      // List folders (default action)
+      if (options.json) {
+        console.log(
+          JSON.stringify(
+            {
+              folders: folders.map((f) => ({
+                id: f.Id,
+                name: f.DisplayName,
+                unread: f.UnreadItemCount,
+                total: f.TotalItemCount,
+                childFolders: f.ChildFolderCount
+              }))
+            },
+            null,
+            2
+          )
+        );
+        return;
+      }
+
+      console.log(`\n\ud83d\udcc1 Mail Folders${options.mailbox ? ` — ${options.mailbox}` : ''}:\n`);
+      console.log('\u2500'.repeat(50));
+
+      for (const folder of folders) {
+        const unreadBadge = folder.UnreadItemCount > 0 ? ` (${folder.UnreadItemCount} unread)` : '';
+        console.log(`  ${folder.DisplayName}${unreadBadge}`);
+        console.log(`    ${folder.TotalItemCount} items`);
+      }
+
+      console.log(`\n${'\u2500'.repeat(50)}`);
+      console.log('\nCommands:');
+      console.log('  m365-agent-cli folders --create "Folder Name"');
+      console.log('  m365-agent-cli folders --rename "Old" --to "New"');
+      console.log('  m365-agent-cli folders --delete "Folder Name"');
+      console.log('');
+    }
+  );

package/src/commands/forward-event.ts

@@ -0,0 +1,49 @@
+import { Command } from 'commander';
+import { resolveGraphAuth } from '../lib/graph-auth.js';
+import { forwardEvent } from '../lib/graph-event.js';
+import { checkReadOnly } from '../lib/utils.js';
+
+export const forwardEventCommand = new Command('forward-event')
+  .description('Forward a calendar event to additional recipients')
+  .alias('forward')
+  .argument('<eventId>', 'The ID of the event to forward')
+  .argument('<recipients...>', 'Email addresses to forward the event to')
+  .option('--comment <text>', 'Optional comment to include in the forwarded invitation')
+  .option('--token <token>', 'Use a specific token')
+  .option('--identity <name>', 'Graph token cache identity (default: default)')
+  .option('--user <email>', 'Mailbox whose calendar contains the event (delegation)')
+  .action(
+    async (
+      eventId: string,
+      recipients: string[],
+      options: { comment?: string; token?: string; identity?: string; user?: string },
+      cmd: any
+    ) => {
+      checkReadOnly(cmd);
+      const authResult = await resolveGraphAuth({ token: options.token, identity: options.identity });
+      if (!authResult.success) {
+        console.error(`Error: ${authResult.error}`);
+        process.exit(1);
+      }
+
+      console.log(`Forwarding event...`);
+      console.log(`  Event ID:   ${eventId}`);
+      console.log(`  Recipients: ${recipients.join(', ')}`);
+      if (options.comment) console.log(`  Comment:    ${options.comment}`);
+
+      const response = await forwardEvent({
+        token: authResult.token!,
+        eventId,
+        toRecipients: recipients,
+        comment: options.comment,
+        user: options.user
+      });
+
+      if (!response.ok) {
+        console.error(`\nError: ${response.error?.message || 'Failed to forward event'}`);
+        process.exit(1);
+      }
+
+      console.log('\n\u2713 Successfully forwarded the event.');
+    }
+  );