@auxiora/calendar-intelligence 1.0.0

package/src/analyzer.ts

@@ -0,0 +1,129 @@
+import type { AnalyzerConfig, CalendarEvent, ConflictInfo, ScheduleAnalysis, TimeSlot } from './types.js';
+
+const DEFAULT_CONFIG: Required<AnalyzerConfig> = {
+  workdayStartHour: 9,
+  workdayEndHour: 17,
+  focusBlockMinMinutes: 60,
+  bufferBetweenMeetingsMinutes: 5,
+};
+
+export class ScheduleAnalyzer {
+  private config: Required<AnalyzerConfig>;
+
+  constructor(config?: AnalyzerConfig) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  analyzeDay(events: CalendarEvent[], date: string): ScheduleAnalysis {
+    const dayEvents = events
+      .filter((e) => e.start.substring(0, 10) === date)
+      .sort((a, b) => a.start.localeCompare(b.start));
+
+    // Detect timezone suffix from events to keep workday bounds consistent
+    const tzSuffix = dayEvents.length > 0 && dayEvents[0].start.endsWith('Z') ? 'Z' : '';
+    const workdayStart = `${date}T${String(this.config.workdayStartHour).padStart(2, '0')}:00:00${tzSuffix}`;
+    const workdayEnd = `${date}T${String(this.config.workdayEndHour).padStart(2, '0')}:00:00${tzSuffix}`;
+
+    const freeSlots = this.findFreeSlots(dayEvents, workdayStart, workdayEnd);
+    const conflicts = this.detectConflicts(dayEvents);
+    const focusBlocks = freeSlots.filter((s) => s.durationMinutes >= this.config.focusBlockMinMinutes);
+
+    const meetingLoadHours = dayEvents.reduce((sum, e) => {
+      const durationMs = new Date(e.end).getTime() - new Date(e.start).getTime();
+      return sum + durationMs / (1000 * 60 * 60);
+    }, 0);
+
+    return {
+      date,
+      events: dayEvents,
+      freeSlots,
+      conflicts,
+      focusBlocks,
+      meetingLoadHours,
+      eventCount: dayEvents.length,
+    };
+  }
+
+  findFreeSlots(
+    events: CalendarEvent[],
+    rangeStart: string,
+    rangeEnd: string,
+    minDurationMinutes?: number,
+  ): TimeSlot[] {
+    const sorted = [...events].sort((a, b) => a.start.localeCompare(b.start));
+    const slots: TimeSlot[] = [];
+    let cursor = new Date(rangeStart).getTime();
+    const end = new Date(rangeEnd).getTime();
+
+    for (const event of sorted) {
+      const eventStart = new Date(event.start).getTime();
+      const eventEnd = new Date(event.end).getTime();
+
+      // Skip events entirely outside the range
+      if (eventEnd <= new Date(rangeStart).getTime() || eventStart >= end) {
+        continue;
+      }
+
+      if (eventStart > cursor) {
+        const gapEnd = Math.min(eventStart, end);
+        const durationMinutes = (gapEnd - cursor) / (1000 * 60);
+        slots.push({
+          start: new Date(cursor).toISOString(),
+          end: new Date(gapEnd).toISOString(),
+          durationMinutes,
+        });
+      }
+
+      cursor = Math.max(cursor, eventEnd);
+    }
+
+    // Gap after last event
+    if (cursor < end) {
+      const durationMinutes = (end - cursor) / (1000 * 60);
+      slots.push({
+        start: new Date(cursor).toISOString(),
+        end: new Date(end).toISOString(),
+        durationMinutes,
+      });
+    }
+
+    if (minDurationMinutes !== undefined) {
+      return slots.filter((s) => s.durationMinutes >= minDurationMinutes);
+    }
+
+    return slots;
+  }
+
+  detectConflicts(events: CalendarEvent[]): ConflictInfo[] {
+    const sorted = [...events].sort((a, b) => a.start.localeCompare(b.start));
+    const conflicts: ConflictInfo[] = [];
+
+    for (let i = 0; i < sorted.length; i++) {
+      for (let j = i + 1; j < sorted.length; j++) {
+        const e1 = sorted[i];
+        const e2 = sorted[j];
+
+        const start1 = new Date(e1.start).getTime();
+        const end1 = new Date(e1.end).getTime();
+        const start2 = new Date(e2.start).getTime();
+        const end2 = new Date(e2.end).getTime();
+
+        if (start1 < end2 && start2 < end1) {
+          const overlapStart = Math.max(start1, start2);
+          const overlapEnd = Math.min(end1, end2);
+          conflicts.push({
+            event1Id: e1.id,
+            event2Id: e2.id,
+            event1Subject: e1.subject,
+            event2Subject: e2.subject,
+            overlapStart: new Date(overlapStart).toISOString(),
+            overlapEnd: new Date(overlapEnd).toISOString(),
+            overlapMinutes: (overlapEnd - overlapStart) / (1000 * 60),
+          });
+        }
+      }
+    }
+
+    return conflicts;
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './analyzer.js';
+export * from './optimizer.js';
+export * from './meeting-prep.js';

package/src/meeting-prep.ts

@@ -0,0 +1,86 @@
+import type { AttendeeContext, CalendarEvent, MeetingBrief } from './types.js';
+
+export class MeetingPrepGenerator {
+  generateBrief(event: CalendarEvent, attendeeContexts?: AttendeeContext[]): MeetingBrief {
+    const agenda = this.extractAgenda(event.body);
+    const attendees = this.buildAttendeeList(event, attendeeContexts);
+    const suggestedTopics = this.generateTopics(event.subject);
+
+    return {
+      eventId: event.id,
+      subject: event.subject,
+      startTime: event.start,
+      attendees,
+      agenda: agenda || undefined,
+      suggestedTopics,
+    };
+  }
+
+  getUpcoming(events: CalendarEvent[], withinMinutes: number, now?: Date): CalendarEvent[] {
+    const currentTime = (now ?? new Date()).getTime();
+    const windowEnd = currentTime + withinMinutes * 60 * 1000;
+
+    return events.filter((event) => {
+      const eventStart = new Date(event.start).getTime();
+      return eventStart > currentTime && eventStart <= windowEnd;
+    });
+  }
+
+  private extractAgenda(body?: string): string | null {
+    if (!body) return null;
+
+    const lines = body.split('\n');
+    const agendaItems: string[] = [];
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (/^[-*]\s+/.test(trimmed) || /^\d+[.)]\s+/.test(trimmed)) {
+        agendaItems.push(trimmed);
+      }
+    }
+
+    return agendaItems.length > 0 ? agendaItems.join('\n') : null;
+  }
+
+  private buildAttendeeList(
+    event: CalendarEvent,
+    contexts?: AttendeeContext[],
+  ): AttendeeContext[] {
+    const contextMap = new Map<string, AttendeeContext>();
+    if (contexts) {
+      for (const ctx of contexts) {
+        contextMap.set(ctx.email, ctx);
+      }
+    }
+
+    return event.attendees.map((attendee) => {
+      const ctx = contextMap.get(attendee.email);
+      return {
+        email: attendee.email,
+        name: attendee.name ?? ctx?.name,
+        lastInteraction: ctx?.lastInteraction,
+        relationship: ctx?.relationship,
+        notes: ctx?.notes,
+      };
+    });
+  }
+
+  private generateTopics(subject: string): string[] {
+    const stopWords = new Set([
+      'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
+      'of', 'with', 'by', 'from', 'is', 'are', 'was', 'were', 'be', 'been',
+      'being', 'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would',
+      'could', 'should', 'may', 'might', 'shall', 'can', 'meeting', 'call',
+      'sync', 'chat', 'discussion', 're', 'fwd', 'fw',
+    ]);
+
+    const words = subject
+      .toLowerCase()
+      .replace(/[^a-z0-9\s]/g, '')
+      .split(/\s+/)
+      .filter((w) => w.length > 2 && !stopWords.has(w));
+
+    const unique = [...new Set(words)];
+    return unique.map((w) => `Discuss ${w}`);
+  }
+}

package/src/optimizer.ts

@@ -0,0 +1,71 @@
+import type { AnalyzerConfig, OptimizationSuggestion, ScheduleAnalysis } from './types.js';
+
+const DEFAULT_BUFFER_MINUTES = 5;
+
+export class ScheduleOptimizer {
+  private bufferMinutes: number;
+
+  constructor(config?: AnalyzerConfig) {
+    this.bufferMinutes = config?.bufferBetweenMeetingsMinutes ?? DEFAULT_BUFFER_MINUTES;
+  }
+
+  suggest(analysis: ScheduleAnalysis): OptimizationSuggestion[] {
+    const suggestions: OptimizationSuggestion[] = [];
+
+    if (analysis.meetingLoadHours > 6) {
+      suggestions.push({
+        type: 'decline',
+        description: 'Meeting load exceeds 6 hours. Consider declining optional meetings to protect your time.',
+        priority: 'high',
+      });
+    }
+
+    if (analysis.meetingLoadHours > 4 && analysis.focusBlocks.length === 0) {
+      suggestions.push({
+        type: 'add-focus-block',
+        description: 'Over 4 hours of meetings with no focus blocks. Block time for deep work.',
+        priority: 'high',
+      });
+    }
+
+    for (const conflict of analysis.conflicts) {
+      suggestions.push({
+        type: 'reschedule',
+        description: `Conflict: "${conflict.event1Subject}" overlaps with "${conflict.event2Subject}" by ${conflict.overlapMinutes} minutes.`,
+        eventId: conflict.event2Id,
+        priority: 'high',
+      });
+    }
+
+    // Back-to-back detection
+    const sorted = [...analysis.events].sort((a, b) => a.start.localeCompare(b.start));
+    for (let i = 0; i < sorted.length - 1; i++) {
+      const currentEnd = new Date(sorted[i].end).getTime();
+      const nextStart = new Date(sorted[i + 1].start).getTime();
+      const gapMinutes = (nextStart - currentEnd) / (1000 * 60);
+      if (gapMinutes >= 0 && gapMinutes < this.bufferMinutes) {
+        suggestions.push({
+          type: 'add-buffer',
+          description: `Only ${gapMinutes} minutes between "${sorted[i].subject}" and "${sorted[i + 1].subject}". Add a buffer.`,
+          eventId: sorted[i + 1].id,
+          priority: 'medium',
+        });
+      }
+    }
+
+    for (const event of analysis.events) {
+      const durationMs = new Date(event.end).getTime() - new Date(event.start).getTime();
+      const durationMinutes = durationMs / (1000 * 60);
+      if (durationMinutes > 60) {
+        suggestions.push({
+          type: 'shorten',
+          description: `"${event.subject}" is ${durationMinutes} minutes. Consider shortening to 45-60 minutes.`,
+          eventId: event.id,
+          priority: 'low',
+        });
+      }
+    }
+
+    return suggestions;
+  }
+}

package/src/types.ts

@@ -0,0 +1,75 @@
+export interface CalendarEvent {
+  id: string;
+  subject: string;
+  start: string; // ISO 8601
+  end: string; // ISO 8601
+  attendees: Attendee[];
+  location?: string;
+  isOnlineMeeting: boolean;
+  organizer?: string;
+  body?: string;
+  isAllDay?: boolean;
+}
+
+export interface Attendee {
+  email: string;
+  name?: string;
+  responseStatus: 'accepted' | 'tentative' | 'declined' | 'none';
+}
+
+export interface TimeSlot {
+  start: string; // ISO 8601
+  end: string; // ISO 8601
+  durationMinutes: number;
+}
+
+export interface ConflictInfo {
+  event1Id: string;
+  event2Id: string;
+  event1Subject: string;
+  event2Subject: string;
+  overlapStart: string;
+  overlapEnd: string;
+  overlapMinutes: number;
+}
+
+export interface ScheduleAnalysis {
+  date: string;
+  events: CalendarEvent[];
+  freeSlots: TimeSlot[];
+  conflicts: ConflictInfo[];
+  focusBlocks: TimeSlot[];
+  meetingLoadHours: number;
+  eventCount: number;
+}
+
+export interface OptimizationSuggestion {
+  type: 'add-focus-block' | 'reschedule' | 'decline' | 'shorten' | 'add-buffer';
+  description: string;
+  eventId?: string;
+  priority: 'high' | 'medium' | 'low';
+}
+
+export interface MeetingBrief {
+  eventId: string;
+  subject: string;
+  startTime: string;
+  attendees: AttendeeContext[];
+  agenda?: string;
+  suggestedTopics: string[];
+}
+
+export interface AttendeeContext {
+  email: string;
+  name?: string;
+  lastInteraction?: string;
+  relationship?: string;
+  notes?: string;
+}
+
+export interface AnalyzerConfig {
+  workdayStartHour?: number; // default 9
+  workdayEndHour?: number; // default 17
+  focusBlockMinMinutes?: number; // default 60
+  bufferBetweenMeetingsMinutes?: number; // default 5
+}

package/tests/analyzer.test.ts

@@ -0,0 +1,150 @@
+import { describe, expect, it } from 'vitest';
+import { ScheduleAnalyzer } from '../src/analyzer.js';
+import type { CalendarEvent } from '../src/types.js';
+
+function makeEvent(overrides: Partial<CalendarEvent> & { id: string; start: string; end: string }): CalendarEvent {
+  return {
+    subject: 'Test Meeting',
+    attendees: [],
+    isOnlineMeeting: false,
+    ...overrides,
+  };
+}
+
+describe('ScheduleAnalyzer', () => {
+  const analyzer = new ScheduleAnalyzer();
+
+  describe('analyzeDay', () => {
+    it('counts events correctly', () => {
+      const events = [
+        makeEvent({ id: '1', start: '2025-03-15T09:00:00Z', end: '2025-03-15T10:00:00Z' }),
+        makeEvent({ id: '2', start: '2025-03-15T11:00:00Z', end: '2025-03-15T12:00:00Z' }),
+        makeEvent({ id: '3', start: '2025-03-16T09:00:00Z', end: '2025-03-16T10:00:00Z' }),
+      ];
+
+      const result = analyzer.analyzeDay(events, '2025-03-15');
+      expect(result.eventCount).toBe(2);
+      expect(result.events).toHaveLength(2);
+    });
+
+    it('finds free slots between events', () => {
+      const events = [
+        makeEvent({ id: '1', start: '2025-03-15T09:00:00Z', end: '2025-03-15T10:00:00Z' }),
+        makeEvent({ id: '2', start: '2025-03-15T14:00:00Z', end: '2025-03-15T15:00:00Z' }),
+      ];
+
+      const result = analyzer.analyzeDay(events, '2025-03-15');
+      expect(result.freeSlots.length).toBeGreaterThanOrEqual(1);
+      // There should be a free slot from 10:00 to 14:00
+      const bigSlot = result.freeSlots.find((s) => s.durationMinutes === 240);
+      expect(bigSlot).toBeDefined();
+    });
+
+    it('respects workday bounds', () => {
+      const customAnalyzer = new ScheduleAnalyzer({ workdayStartHour: 8, workdayEndHour: 18 });
+      const events = [
+        makeEvent({ id: '1', start: '2025-03-15T10:00:00Z', end: '2025-03-15T11:00:00Z' }),
+      ];
+
+      const result = customAnalyzer.analyzeDay(events, '2025-03-15');
+      // Free slot before: 08:00-10:00 (120 min), after: 11:00-18:00 (420 min)
+      const beforeSlot = result.freeSlots.find((s) => s.durationMinutes === 120);
+      const afterSlot = result.freeSlots.find((s) => s.durationMinutes === 420);
+      expect(beforeSlot).toBeDefined();
+      expect(afterSlot).toBeDefined();
+    });
+
+    it('detects overlapping events as conflicts', () => {
+      const events = [
+        makeEvent({ id: '1', subject: 'Meeting A', start: '2025-03-15T09:00:00Z', end: '2025-03-15T10:30:00Z' }),
+        makeEvent({ id: '2', subject: 'Meeting B', start: '2025-03-15T10:00:00Z', end: '2025-03-15T11:00:00Z' }),
+      ];
+
+      const result = analyzer.analyzeDay(events, '2025-03-15');
+      expect(result.conflicts).toHaveLength(1);
+      expect(result.conflicts[0].overlapMinutes).toBe(30);
+    });
+
+    it('identifies focus blocks (slots >= 60min)', () => {
+      const events = [
+        makeEvent({ id: '1', start: '2025-03-15T09:00:00Z', end: '2025-03-15T09:30:00Z' }),
+        makeEvent({ id: '2', start: '2025-03-15T09:45:00Z', end: '2025-03-15T10:00:00Z' }),
+        makeEvent({ id: '3', start: '2025-03-15T14:00:00Z', end: '2025-03-15T15:00:00Z' }),
+      ];
+
+      const result = analyzer.analyzeDay(events, '2025-03-15');
+      // 09:30-09:45 = 15min (not focus), 10:00-14:00 = 240min (focus), 15:00-17:00 = 120min (focus)
+      expect(result.focusBlocks.length).toBe(2);
+      expect(result.focusBlocks.every((b) => b.durationMinutes >= 60)).toBe(true);
+    });
+
+    it('calculates meeting load hours', () => {
+      const events = [
+        makeEvent({ id: '1', start: '2025-03-15T09:00:00Z', end: '2025-03-15T10:00:00Z' }),
+        makeEvent({ id: '2', start: '2025-03-15T11:00:00Z', end: '2025-03-15T12:30:00Z' }),
+      ];
+
+      const result = analyzer.analyzeDay(events, '2025-03-15');
+      expect(result.meetingLoadHours).toBe(2.5);
+    });
+  });
+
+  describe('findFreeSlots', () => {
+    it('finds gaps correctly', () => {
+      const events = [
+        makeEvent({ id: '1', start: '2025-03-15T09:00:00Z', end: '2025-03-15T10:00:00Z' }),
+        makeEvent({ id: '2', start: '2025-03-15T12:00:00Z', end: '2025-03-15T13:00:00Z' }),
+      ];
+
+      const slots = analyzer.findFreeSlots(events, '2025-03-15T08:00:00Z', '2025-03-15T17:00:00Z');
+      expect(slots).toHaveLength(3);
+      // 08-09 (60min), 10-12 (120min), 13-17 (240min)
+      expect(slots[0].durationMinutes).toBe(60);
+      expect(slots[1].durationMinutes).toBe(120);
+      expect(slots[2].durationMinutes).toBe(240);
+    });
+
+    it('filters by minimum duration', () => {
+      const events = [
+        makeEvent({ id: '1', start: '2025-03-15T09:00:00Z', end: '2025-03-15T10:00:00Z' }),
+        makeEvent({ id: '2', start: '2025-03-15T10:15:00Z', end: '2025-03-15T11:00:00Z' }),
+      ];
+
+      const slots = analyzer.findFreeSlots(events, '2025-03-15T09:00:00Z', '2025-03-15T12:00:00Z', 30);
+      // 10:00-10:15 = 15min (excluded), 11:00-12:00 = 60min (included)
+      expect(slots).toHaveLength(1);
+      expect(slots[0].durationMinutes).toBe(60);
+    });
+
+    it('handles empty event list (whole range is free)', () => {
+      const slots = analyzer.findFreeSlots([], '2025-03-15T09:00:00Z', '2025-03-15T17:00:00Z');
+      expect(slots).toHaveLength(1);
+      expect(slots[0].durationMinutes).toBe(480);
+    });
+  });
+
+  describe('detectConflicts', () => {
+    it('returns empty for non-overlapping events', () => {
+      const events = [
+        makeEvent({ id: '1', start: '2025-03-15T09:00:00Z', end: '2025-03-15T10:00:00Z' }),
+        makeEvent({ id: '2', start: '2025-03-15T10:00:00Z', end: '2025-03-15T11:00:00Z' }),
+        makeEvent({ id: '3', start: '2025-03-15T14:00:00Z', end: '2025-03-15T15:00:00Z' }),
+      ];
+
+      const conflicts = analyzer.detectConflicts(events);
+      expect(conflicts).toHaveLength(0);
+    });
+
+    it('detects multiple conflicts', () => {
+      const events = [
+        makeEvent({ id: '1', subject: 'A', start: '2025-03-15T09:00:00Z', end: '2025-03-15T10:30:00Z' }),
+        makeEvent({ id: '2', subject: 'B', start: '2025-03-15T10:00:00Z', end: '2025-03-15T11:00:00Z' }),
+        makeEvent({ id: '3', subject: 'C', start: '2025-03-15T10:15:00Z', end: '2025-03-15T11:30:00Z' }),
+      ];
+
+      const conflicts = analyzer.detectConflicts(events);
+      // A overlaps B, A overlaps C, B overlaps C
+      expect(conflicts).toHaveLength(3);
+    });
+  });
+});

package/tests/meeting-prep.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+import { MeetingPrepGenerator } from '../src/meeting-prep.js';
+import type { AttendeeContext, CalendarEvent } from '../src/types.js';
+
+function makeEvent(overrides: Partial<CalendarEvent> = {}): CalendarEvent {
+  return {
+    id: 'evt-1',
+    subject: 'Project Review',
+    start: '2025-03-15T10:00:00Z',
+    end: '2025-03-15T11:00:00Z',
+    attendees: [
+      { email: 'alice@example.com', name: 'Alice', responseStatus: 'accepted' },
+      { email: 'bob@example.com', name: 'Bob', responseStatus: 'tentative' },
+    ],
+    isOnlineMeeting: true,
+    ...overrides,
+  };
+}
+
+describe('MeetingPrepGenerator', () => {
+  const generator = new MeetingPrepGenerator();
+
+  describe('generateBrief', () => {
+    it('extracts attendees', () => {
+      const event = makeEvent();
+      const brief = generator.generateBrief(event);
+      expect(brief.attendees).toHaveLength(2);
+      expect(brief.attendees[0].email).toBe('alice@example.com');
+      expect(brief.attendees[1].email).toBe('bob@example.com');
+    });
+
+    it('extracts agenda from body', () => {
+      const event = makeEvent({
+        body: 'Hello team,\n\nAgenda:\n- Review Q1 results\n- Discuss roadmap\n- Action items\n\nThanks',
+      });
+      const brief = generator.generateBrief(event);
+      expect(brief.agenda).toBeDefined();
+      expect(brief.agenda).toContain('Review Q1 results');
+      expect(brief.agenda).toContain('Discuss roadmap');
+      expect(brief.agenda).toContain('Action items');
+    });
+
+    it('generates suggested topics from subject', () => {
+      const event = makeEvent({ subject: 'Q1 Budget Planning Review' });
+      const brief = generator.generateBrief(event);
+      expect(brief.suggestedTopics.length).toBeGreaterThan(0);
+      expect(brief.suggestedTopics.some((t) => t.toLowerCase().includes('budget'))).toBe(true);
+    });
+
+    it('merges attendee context when provided', () => {
+      const event = makeEvent();
+      const contexts: AttendeeContext[] = [
+        { email: 'alice@example.com', relationship: 'manager', notes: 'Decision maker' },
+      ];
+      const brief = generator.generateBrief(event, contexts);
+      const alice = brief.attendees.find((a) => a.email === 'alice@example.com');
+      expect(alice?.relationship).toBe('manager');
+      expect(alice?.notes).toBe('Decision maker');
+    });
+  });
+
+  describe('getUpcoming', () => {
+    it('returns events within window', () => {
+      const now = new Date('2025-03-15T09:00:00Z');
+      const events = [
+        makeEvent({ id: '1', start: '2025-03-15T09:15:00Z', end: '2025-03-15T10:00:00Z' }),
+        makeEvent({ id: '2', start: '2025-03-15T09:45:00Z', end: '2025-03-15T10:30:00Z' }),
+        makeEvent({ id: '3', start: '2025-03-15T12:00:00Z', end: '2025-03-15T13:00:00Z' }),
+      ];
+
+      const upcoming = generator.getUpcoming(events, 60, now);
+      expect(upcoming).toHaveLength(2);
+      expect(upcoming.map((e) => e.id)).toEqual(['1', '2']);
+    });
+
+    it('excludes past events', () => {
+      const now = new Date('2025-03-15T10:30:00Z');
+      const events = [
+        makeEvent({ id: '1', start: '2025-03-15T09:00:00Z', end: '2025-03-15T10:00:00Z' }),
+        makeEvent({ id: '2', start: '2025-03-15T10:00:00Z', end: '2025-03-15T11:00:00Z' }),
+        makeEvent({ id: '3', start: '2025-03-15T11:00:00Z', end: '2025-03-15T12:00:00Z' }),
+      ];
+
+      const upcoming = generator.getUpcoming(events, 60, now);
+      // Event 1 started in the past, Event 2 already started, only Event 3 is upcoming
+      expect(upcoming).toHaveLength(1);
+      expect(upcoming[0].id).toBe('3');
+    });
+  });
+});

package/tests/optimizer.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+import { ScheduleOptimizer } from '../src/optimizer.js';
+import type { ScheduleAnalysis, CalendarEvent, ConflictInfo, TimeSlot } from '../src/types.js';
+
+function makeAnalysis(overrides: Partial<ScheduleAnalysis> = {}): ScheduleAnalysis {
+  return {
+    date: '2025-03-15',
+    events: [],
+    freeSlots: [],
+    conflicts: [],
+    focusBlocks: [],
+    meetingLoadHours: 0,
+    eventCount: 0,
+    ...overrides,
+  };
+}
+
+function makeEvent(id: string, start: string, end: string, subject = 'Meeting'): CalendarEvent {
+  return { id, subject, start, end, attendees: [], isOnlineMeeting: false };
+}
+
+describe('ScheduleOptimizer', () => {
+  const optimizer = new ScheduleOptimizer();
+
+  it('suggests decline when meeting load > 6 hours', () => {
+    const analysis = makeAnalysis({ meetingLoadHours: 7 });
+    const suggestions = optimizer.suggest(analysis);
+    expect(suggestions.some((s) => s.type === 'decline' && s.priority === 'high')).toBe(true);
+  });
+
+  it('suggests add-focus-block when no focus blocks and load > 4', () => {
+    const analysis = makeAnalysis({ meetingLoadHours: 5, focusBlocks: [] });
+    const suggestions = optimizer.suggest(analysis);
+    expect(suggestions.some((s) => s.type === 'add-focus-block' && s.priority === 'high')).toBe(true);
+  });
+
+  it('suggests reschedule for conflicts', () => {
+    const conflict: ConflictInfo = {
+      event1Id: '1',
+      event2Id: '2',
+      event1Subject: 'A',
+      event2Subject: 'B',
+      overlapStart: '2025-03-15T10:00:00Z',
+      overlapEnd: '2025-03-15T10:30:00Z',
+      overlapMinutes: 30,
+    };
+    const analysis = makeAnalysis({ conflicts: [conflict] });
+    const suggestions = optimizer.suggest(analysis);
+    expect(suggestions.some((s) => s.type === 'reschedule' && s.priority === 'high')).toBe(true);
+  });
+
+  it('suggests buffer for back-to-back meetings', () => {
+    const events = [
+      makeEvent('1', '2025-03-15T09:00:00Z', '2025-03-15T10:00:00Z', 'First'),
+      makeEvent('2', '2025-03-15T10:02:00Z', '2025-03-15T11:00:00Z', 'Second'),
+    ];
+    const analysis = makeAnalysis({ events });
+    const suggestions = optimizer.suggest(analysis);
+    expect(suggestions.some((s) => s.type === 'add-buffer' && s.priority === 'medium')).toBe(true);
+  });
+
+  it('returns empty for light schedule', () => {
+    const events = [
+      makeEvent('1', '2025-03-15T10:00:00Z', '2025-03-15T10:30:00Z'),
+    ];
+    const focusBlock: TimeSlot = {
+      start: '2025-03-15T10:30:00Z',
+      end: '2025-03-15T17:00:00Z',
+      durationMinutes: 390,
+    };
+    const analysis = makeAnalysis({
+      events,
+      meetingLoadHours: 0.5,
+      focusBlocks: [focusBlock],
+    });
+    const suggestions = optimizer.suggest(analysis);
+    expect(suggestions).toHaveLength(0);
+  });
+});