@shin1ohno/sage 0.7.8 → 0.8.4

package/dist/integrations/calendar-source-manager.d.ts

@@ -0,0 +1,302 @@
+/**
+ * Calendar Source Manager
+ * Requirements: 9, 11
+ * Design: .claude/specs/google-calendar-api/design.md (CalendarSourceManager section)
+ *
+ * Manages multiple calendar sources (EventKit, Google Calendar) with automatic
+ * source selection, fallback handling, and unified MCP tool interface.
+ */
+import { CalendarService } from './calendar-service.js';
+import type { CalendarEvent, AvailableSlot } from './calendar-service.js';
+import { GoogleCalendarService } from './google-calendar-service.js';
+import type { CreateEventRequest } from './google-calendar-service.js';
+import type { UserConfig } from '../types/config.js';
+import type { SyncResult, SyncStatus } from '../types/google-calendar-types.js';
+/**
+ * Request interface for finding available slots
+ * Requirement: 7
+ */
+export interface FindSlotsRequest {
+    startDate: string;
+    endDate: string;
+    minDurationMinutes?: number;
+    maxDurationMinutes?: number;
+    workingHours?: {
+        start: string;
+        end: string;
+    };
+}
+/**
+ * Options for CalendarSourceManager constructor
+ */
+export interface CalendarSourceManagerOptions {
+    calendarService?: CalendarService;
+    googleCalendarService?: GoogleCalendarService;
+    config?: UserConfig;
+}
+/**
+ * Calendar Source Manager
+ *
+ * Manages multiple calendar sources (EventKit, Google Calendar) with:
+ * - Automatic source detection and selection
+ * - Unified event operations across sources
+ * - Fallback handling for source failures
+ * - Event deduplication across sources
+ */
+export declare class CalendarSourceManager {
+    private calendarService?;
+    private googleCalendarService?;
+    private config?;
+    /**
+     * Constructor
+     *
+     * @param options - Optional services and config
+     */
+    constructor(options?: CalendarSourceManagerOptions);
+    /**
+     * Detect available calendar sources
+     * Requirement: 9 (Platform detection and source availability)
+     *
+     * Uses detectPlatform() pattern from CalendarService to determine which
+     * calendar sources are available on the current platform.
+     *
+     * @returns Object indicating which sources are available
+     */
+    detectAvailableSources(): Promise<{
+        eventkit: boolean;
+        google: boolean;
+    }>;
+    /**
+     * Enable a calendar source
+     * Requirement: 11 (Calendar source management)
+     *
+     * Updates config to enable the specified source and validates that
+     * at least one source remains enabled.
+     *
+     * @param source - Calendar source to enable ('eventkit' | 'google')
+     * @throws Error if config is not available
+     */
+    enableSource(source: 'eventkit' | 'google'): Promise<void>;
+    /**
+     * Disable a calendar source
+     * Requirement: 11 (Calendar source management)
+     *
+     * Updates config to disable the specified source and validates that
+     * at least one source remains enabled.
+     *
+     * @param source - Calendar source to disable ('eventkit' | 'google')
+     * @throws Error if disabling would leave no sources enabled
+     */
+    disableSource(source: 'eventkit' | 'google'): Promise<void>;
+    /**
+     * Get enabled calendar sources
+     * Requirement: 9 (Source configuration reading)
+     *
+     * Reads from config.calendar.sources to determine which sources are enabled.
+     *
+     * @returns Array of enabled source names
+     */
+    getEnabledSources(): ('eventkit' | 'google')[];
+    /**
+     * Get events from enabled calendar sources
+     * Requirement: 7, 10, 11 (Multi-source event retrieval with deduplication and fallback)
+     *
+     * Fetches events from all enabled sources with fallback handling and deduplication.
+     * - Task 17a: Basic parallel fetching
+     * - Task 17b: Deduplication and fallback logic
+     *
+     * Fallback behavior: If one source fails, continues with other sources.
+     * Only throws if ALL sources fail.
+     *
+     * @param startDate - Start date (ISO 8601)
+     * @param endDate - End date (ISO 8601)
+     * @param calendarId - Optional calendar ID filter
+     * @returns Array of deduplicated calendar events from all enabled sources
+     */
+    getEvents(startDate: string, endDate: string, calendarId?: string): Promise<CalendarEvent[]>;
+    /**
+     * Check if two events are duplicates
+     * Requirement: 10 (Event deduplication)
+     *
+     * Uses two methods to detect duplicates:
+     * 1. iCalUID comparison (most reliable, RFC 5545 standard)
+     * 2. Title + time matching (fallback for events without iCalUID)
+     *
+     * Note: iCalUID support will be added in Task 24. Until then, this uses
+     * type assertions to access the optional iCalUID property.
+     *
+     * @param event1 - First event
+     * @param event2 - Second event
+     * @returns True if events are duplicates
+     */
+    private areEventsDuplicate;
+    /**
+     * Deduplicate events array
+     * Requirement: 10 (Event deduplication)
+     *
+     * Removes duplicate events keeping the first occurrence.
+     * Uses areEventsDuplicate() for comparison.
+     *
+     * @param events - Array of events to deduplicate
+     * @returns Array of unique events
+     */
+    private deduplicateEvents;
+    /**
+     * Create event in preferred calendar source
+     * Requirement: 3, 10, 11 (Multi-source event creation with routing and fallback)
+     *
+     * Creates an event in the specified source with fallback handling:
+     * 1. If preferredSource is specified, try that source first
+     * 2. If preferred source fails or not specified, try other enabled sources
+     * 3. Throws error if all sources fail
+     *
+     * Note: EventKit does not support event creation in current implementation,
+     * so only Google Calendar is supported for event creation.
+     *
+     * @param request - Event creation request
+     * @param preferredSource - Preferred source ('eventkit' | 'google')
+     * @returns Created calendar event
+     * @throws Error if all sources fail or no sources are enabled
+     */
+    createEvent(request: CreateEventRequest, preferredSource?: 'eventkit' | 'google'): Promise<CalendarEvent>;
+    /**
+     * Delete event from calendar source
+     * Requirement: 5, 10, 11 (Multi-source event deletion with routing and error handling)
+     *
+     * Deletes an event from the specified source, or attempts deletion
+     * from all sources if source is not specified.
+     *
+     * If source specified:
+     * - Deletes from that source only
+     * - Throws error if source is not enabled or service not available
+     *
+     * If source not specified:
+     * - Attempts to delete from ALL enabled sources
+     * - Event may exist in both EventKit and Google Calendar (duplicate)
+     * - Uses Promise.allSettled() to try all sources
+     * - 404 errors (event not found) do not cause failure
+     * - Only throws if ALL attempts fail with non-404 errors
+     *
+     * @param eventId - Event ID to delete
+     * @param source - Optional source ('eventkit' | 'google')
+     * @throws Error if source specified and not available, or all sources fail with non-404 errors
+     */
+    deleteEvent(eventId: string, source?: 'eventkit' | 'google'): Promise<void>;
+    /**
+     * Find available time slots considering all enabled sources
+     * Requirement: 7 (Multi-source slot detection)
+     * Task 20a: Basic filtering implementation
+     * Task 20b: Suitability calculation integration
+     *
+     * Fetches events from all enabled sources, merges and deduplicates,
+     * then calculates available slots based on working hours and preferences.
+     * Applies suitability scoring and sorts by suitability.
+     *
+     * @param request - Slot search request
+     * @returns Array of available time slots sorted by suitability
+     */
+    findAvailableSlots(request: FindSlotsRequest): Promise<AvailableSlot[]>;
+    /**
+     * Get default working hours
+     * Requirement: 7
+     *
+     * Returns working hours from config or default (09:00 - 18:00)
+     *
+     * @returns Working hours configuration
+     */
+    private getDefaultWorkingHours;
+    /**
+     * Calculate suitability for all slots
+     * Requirement: 7 (Task 20b)
+     *
+     * Applies suitability scoring to slots based on:
+     * - Day type (deep work vs meeting heavy) from config
+     * - Time of day (morning slots preferred)
+     * - Slot duration (longer slots better for deep work)
+     *
+     * @param slots - Array of slots to score
+     * @returns Array of slots with suitability applied
+     */
+    private calculateSuitabilityForSlots;
+    /**
+     * Find available slots for a single day
+     * Requirement: 7
+     *
+     * Calculates gaps between events within working hours for a specific day.
+     *
+     * @param date - Date to find slots for
+     * @param events - All events (sorted by start time)
+     * @param workingHours - Working hours configuration
+     * @param minDuration - Minimum slot duration in minutes
+     * @param maxDuration - Maximum slot duration in minutes
+     * @returns Array of available slots for this day
+     */
+    private findDaySlots;
+    /**
+     * Sync calendars between sources
+     * Requirement: 8 (Calendar synchronization)
+     *
+     * Synchronizes events between EventKit and Google Calendar when both
+     * sources are enabled. Handles conflicts and provides sync results.
+     *
+     * Note: This is a stub implementation. Full sync logic can be added later.
+     * Currently, it validates that both sources are enabled and returns empty results.
+     *
+     * @returns Sync result with statistics and errors
+     * @throws Error if both sources are not enabled
+     */
+    syncCalendars(): Promise<SyncResult>;
+    /**
+     * Get sync status between calendar sources
+     * Requirement: 8 (Calendar synchronization)
+     *
+     * Returns the current sync status including last sync time,
+     * next scheduled sync, and source availability.
+     *
+     * Note: This is a stub implementation. lastSyncTime tracking will be added
+     * when full sync implementation is completed.
+     *
+     * @returns Sync status information
+     */
+    getSyncStatus(): Promise<SyncStatus>;
+    /**
+     * Health check for calendar sources
+     * Requirement: 10, 11 (Health check for both sources)
+     * Task 22: Implementation
+     *
+     * Checks availability and health of all calendar sources by calling
+     * their respective isAvailable() methods. Returns a status object
+     * indicating which sources are currently healthy and available.
+     *
+     * This method never throws errors - it catches all failures and returns
+     * false for sources that are unavailable or unhealthy.
+     *
+     * @returns Object indicating health status of each source
+     */
+    healthCheck(): Promise<{
+        eventkit: boolean;
+        google: boolean;
+    }>;
+    /**
+     * Respond to a calendar event
+     * Requirement: 6 (Event response/RSVP)
+     *
+     * Routes event response to the appropriate calendar source.
+     * Supports EventKit (via CalendarEventResponseService) and Google Calendar.
+     * If source is not specified, attempts to determine source by fetching
+     * the event from all enabled sources.
+     *
+     * @param eventId - Event ID
+     * @param response - Response type: 'accept', 'decline', or 'tentative'
+     * @param source - Optional source routing ('eventkit' or 'google')
+     * @param calendarId - Optional calendar ID (for Google Calendar)
+     * @returns Success status and message
+     * @throws Error if event not found or response fails
+     */
+    respondToEvent(eventId: string, response: 'accept' | 'decline' | 'tentative', source?: 'eventkit' | 'google', calendarId?: string): Promise<{
+        success: boolean;
+        message: string;
+        source?: string;
+    }>;
+}
+//# sourceMappingURL=calendar-source-manager.d.ts.map

package/dist/integrations/calendar-source-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendar-source-manager.d.ts","sourceRoot":"","sources":["../../src/integrations/calendar-source-manager.ts"],"names":[],"mappings":"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"}