From 43e5296db49fc817834ab30c90926a9af0d830e7 Mon Sep 17 00:00:00 2001 From: mARTin Date: Sun, 25 Jan 2026 15:11:32 +0100 Subject: [PATCH] docs(03): create gap closure plans for calendar integration Address gaps found in verification: - Fix Google and Apple OAuth callbacks to use real API token exchanges - Complete calendar event fetching with real API integrations - Implement bidirectional sync with actual database/calendar operations - Enable functional calendar connection UI with real OAuth triggers --- .../03-calendar-integration/03-04-PLAN.md | 142 +++++++++++++ .../03-calendar-integration/03-05-PLAN.md | 200 ++++++++++++++++++ .../03-calendar-integration/03-06-PLAN.md | 162 ++++++++++++++ 3 files changed, 504 insertions(+) create mode 100644 .planning/phases/03-calendar-integration/03-04-PLAN.md create mode 100644 .planning/phases/03-calendar-integration/03-05-PLAN.md create mode 100644 .planning/phases/03-calendar-integration/03-06-PLAN.md diff --git a/.planning/phases/03-calendar-integration/03-04-PLAN.md b/.planning/phases/03-calendar-integration/03-04-PLAN.md new file mode 100644 index 0000000..cb4a0ae --- /dev/null +++ b/.planning/phases/03-calendar-integration/03-04-PLAN.md @@ -0,0 +1,142 @@ +--- +phase: 03-calendar-integration +plan: 04 +type: execute +wave: 1 +depends_on: [] +files_modified: + - src/app/api/calendar/google/oauth/route.ts + - src/app/api/calendar/apple/oauth/route.ts + - src/lib/google-calendar.ts + - src/lib/apple-calendar.ts + - src/lib/calendar-sync.ts + - prisma/schema.prisma +autonomous: true +gap_closure: true + +must_haves: + truths: + - "User can connect their Google Calendar account" + - "User can connect their Apple Calendar account" + - "User can view calendar events alongside tasks in weekly view" + - "User can manage calendar connection settings from the application" + - "User's tasks and calendar events are synchronized bidirectionally" + artifacts: + - path: "src/app/api/calendar/google/oauth/route.ts" + provides: "Real Google API token exchange implementation" + - path: "src/app/api/calendar/apple/oauth/route.ts" + provides: "Real Apple API token exchange implementation" + - path: "src/lib/google-calendar.ts" + provides: "Real Google Calendar API integration" + - path: "src/lib/apple-calendar.ts" + provides: "Real Apple Calendar API integration" + - path: "src/lib/calendar-sync.ts" + provides: "Complete bidirectional sync implementation" + - path: "prisma/schema.prisma" + provides: "CalendarConnection model with all necessary fields" + key_links: + - from: "src/app/api/calendar/google/oauth/route.ts" + to: "src/lib/google-calendar.ts" + via: "token exchange via initializeOAuth function" + pattern: "initializeOAuth.*google" + - from: "src/app/api/calendar/apple/oauth/route.ts" + to: "src/lib/apple-calendar.ts" + via: "token exchange via initializeOAuth function" + pattern: "initializeOAuth.*apple" + - from: "src/lib/calendar-sync.ts" + to: "prisma/calendarConnection" + via: "database operations for storing tokens" + pattern: "prisma\\.calendarConnection" +--- + +# Gap Closure: Calendar OAuth Implementation + +## Objective +Fix incomplete Google and Apple Calendar OAuth implementations to enable real calendar account connections. + +## Purpose +Enable users to securely connect their Google and Apple Calendar accounts through proper OAuth flows. + +## Output +Functional OAuth endpoints that exchange authorization codes for real tokens and store them securely in the database. + +## Tasks + + + Fix Google OAuth Callback with Real Token Exchange + src/app/api/calendar/google/oauth/route.ts + + Replace the current placeholder implementation with a real token exchange: + + 1. Remove hardcoded mock tokens from the implementation + 2. Implement real API call to exchange the authorization code for access and refresh tokens using the Google OAuth2 API + 3. Store valid tokens in the database using Prisma ORM instead of console logging + 4. Add proper error handling for token exchange failures with informative messages + 5. Implement token validation to ensure they're valid before saving + + The implementation should: + - Call the Google OAuth2 token endpoint with the authorization code + - Handle successful token exchange results + - Handle and log token exchange errors appropriately + - Store the tokens in the CalendarConnection database record + + Run `curl -X GET "http://localhost:3000/api/calendar/google/oauth?code=valid_code"` and verify tokens are stored in database instead of just console logged + Google OAuth callback endpoint exchanges real tokens and stores them in database + + + + Fix Apple OAuth Callback with Real Token Exchange + src/app/api/calendar/apple/oauth/route.ts + + Replace the current placeholder implementation with a real token exchange: + + 1. Remove hardcoded mock tokens from the implementation + 2. Implement real API call to exchange the authorization code for access and refresh tokens using Apple's OAuth2 API + 3. Store valid tokens in the database using Prisma ORM instead of console logging + 4. Add proper error handling for token exchange failures with informative messages + 5. Implement token validation to ensure they're valid before saving + + The implementation should: + - Make a POST request to Apple's token endpoint with code, client_id, client_secret, and redirect_uri + - Handle successful token exchange results + - Handle and log token exchange errors appropriately + - Store the tokens in the CalendarConnection database record + + Run `curl -X GET "http://localhost:3000/api/calendar/apple/oauth?code=valid_code"` and verify tokens are stored in database instead of just console logged + Apple OAuth callback endpoint exchanges real tokens and stores them in database + + + + Implement Database Storage for OAuth Tokens + prisma/schema.prisma + + Update the CalendarConnection model to include necessary fields for storing OAuth tokens properly: + + 1. Ensure the model has all required fields for storing tokens (access_token, refresh_token, expires_at) + 2. Add proper database constraints and validations + 3. Ensure relationships with User model are properly defined + + Currently, we have proper fields, but we need to make sure: + - The model properly supports both Google and Apple token formats + - Fields are properly indexed for performance + - The relationship with User is correctly defined + + Check that prisma/schema.prisma defines CalendarConnection model with userId, provider, accessToken, refreshToken, expiresAt fields + CalendarConnection model properly defined with all required fields for OAuth token storage + + + +## Verification + +After completing these tasks, the following checks should pass: +- Google OAuth callback exchanges real tokens instead of using placeholders +- Apple OAuth callback exchanges real tokens instead of using placeholders +- OAuth tokens are stored in the database properly instead of just logged +- All error cases have proper handling and reporting + +## Success Criteria + +All gaps identified in the VERIFICATION.md for Google and Apple OAuth implementations are resolved: +- OAuth endpoints use real API token exchange instead of placeholder implementations +- OAuth tokens are securely stored in the database +- Proper error handling for token exchange failures \ No newline at end of file diff --git a/.planning/phases/03-calendar-integration/03-05-PLAN.md b/.planning/phases/03-calendar-integration/03-05-PLAN.md new file mode 100644 index 0000000..50d9445 --- /dev/null +++ b/.planning/phases/03-calendar-integration/03-05-PLAN.md @@ -0,0 +1,200 @@ +--- +phase: 03-calendar-integration +plan: 05 +type: execute +wave: 1 +depends_on: [] +files_modified: + - src/lib/calendar-events.ts + - src/lib/google-calendar.ts + - src/lib/apple-calendar.ts + - src/lib/calendar-sync.ts + - src/components/WeeklyView.tsx +autonomous: true +gap_closure: true + +must_haves: + truths: + - "User can connect their Google Calendar account" + - "User can connect their Apple Calendar account" + - "User can view calendar events alongside tasks in weekly view" + - "User can manage calendar connection settings from the application" + - "User's tasks and calendar events are synchronized bidirectionally" + artifacts: + - path: "src/lib/calendar-events.ts" + provides: "Real calendar event fetching from APIs" + - path: "src/lib/google-calendar.ts" + provides: "Real Google Calendar API integration functions" + - path: "src/lib/apple-calendar.ts" + provides: "Real Apple Calendar API integration functions" + - path: "src/lib/calendar-sync.ts" + provides: "Complete bidirectional sync implementation" + - path: "src/components/WeeklyView.tsx" + provides: "Dynamic calendar event display from connected calendars" + key_links: + - from: "src/components/WeeklyView.tsx" + to: "src/lib/calendar-events.ts" + via: "fetching calendar events for display" + pattern: "getCalendarEvents" + - from: "src/lib/calendar-events.ts" + to: "src/lib/google-calendar.ts" + via: "fetching events from Google Calendar API" + pattern: "getUpcomingEvents.*google" + - from: "src/lib/calendar-events.ts" + to: "src/lib/apple-calendar.ts" + via: "fetching events from Apple Calendar API" + pattern: "getUserCalendars.*apple" + - from: "src/lib/calendar-sync.ts" + to: "src/lib/google-calendar.ts" + via: "importing events from Google Calendar API" + pattern: "getUpcomingEvents.*google" + - from: "src/lib/calendar-sync.ts" + to: "src/lib/apple-calendar.ts" + via: "importing events from Apple Calendar API" + pattern: "getUserCalendars.*apple" +--- + +# Gap Closure: Calendar Event Fetching and Sync Implementation + +## Objective +Complete calendar event fetching and bidirectional sync implementations to enable real calendar integration. + +## Purpose +Enable users to view real calendar events in the weekly view and synchronize tasks with their connected calendars. + +## Output +Functional calendar event fetching and bidirectional sync that integrates with real calendar APIs. + +## Tasks + + + Fix Calendar Events Fetching to Use Real APIs + src/lib/calendar-events.ts + + Replace mock implementations with real API integration: + + 1. Remove hardcoded mock data from getCalendarEvents function + 2. Implement real API calls to fetch calendar events from connected providers + 3. Integrate with both Google and Apple calendar libraries + 4. Properly handle different calendar event structures from different providers + 5. Add error handling for network failures or authentication issues + 6. Implement caching strategy to avoid excessive API calls + + The implementation should: + - Check for connected calendars and their providers + - Call appropriate functions from google-calendar.ts or apple-calendar.ts + - Aggregate events from all connected calendars + - Transform events to standardized format for display + + Run `npm test` for calendar events utility and verify it can fetch real events instead of returning mock data + Calendar events utility fetches real events from connected calendars + + + + Complete Google Calendar API Integration + src/lib/google-calendar.ts + + Ensure the Google Calendar library properly implements real API integration: + + 1. Fix any type annotation issues (remove 'any' types where possible) + 2. Ensure proper API calls to Google Calendar API with access tokens + 3. Add proper response handling for different Google API responses + 4. Add retry logic for transient network errors + 5. Implement proper error handling for unauthorized access or quota limits + + The implementation should: + - Use actual Google API endpoints through googleapis library + - Handle API response structures correctly + - Provide clear error messages when API calls fail + - Follow Google's API best practices + + Run `npm test` for google-calendar.ts and verify all functions properly interact with Google Calendar API + Google Calendar API integration functions work with real Google Calendar API calls + + + + Complete Apple Calendar API Integration + src/lib/apple-calendar.ts + + Ensure the Apple Calendar library properly implements real API integration: + + 1. Fix any type annotation issues (remove 'any' types where possible) + 2. Implement proper API calls to Apple Calendar API + 3. Add proper response handling for Apple API responses + 4. Add retry logic for transient network errors + 5. Implement proper error handling for unauthorized access or API rate limits + + The implementation should: + - Make actual HTTP requests to Apple Calendar API endpoints + - Handle Apple's authentication flow properly + - Provide clear error messages when API calls fail + - Follow Apple's API best practices + + Run `npm test` for apple-calendar.ts and verify all functions properly interact with Apple Calendar API + Apple Calendar API integration functions work with real Apple Calendar API calls + + + + Complete Bidirectional Sync Implementation + src/lib/calendar-sync.ts + + Replace console.log operations with actual database and calendar API operations: + + 1. Implement actual database storage of sync results instead of console logging + 2. Implement actual API calls to import calendar events into tasks + 3. Implement actual API calls to export tasks to calendar events + 4. Add proper transaction handling for data consistency + 5. Add conflict resolution for duplicate events/tasks + 6. Implement proper error handling for sync failures + 7. Add metrics collection for sync operations + + The implementation should: + - Use Prisma ORM to persist sync results + - Call appropriate functions from google-calendar.ts and apple-calendar.ts to fetch/submit events + - Handle both directions of sync (calendar → tasks and tasks → calendar) + - Provide detailed sync results with counts and conflicts + + Run `npm test` for calendar-sync.ts and verify it performs actual operations instead of just console logging + Bidirectional sync performs actual database/calendar API operations + + + + Update Weekly View to Display Real Calendar Events + src/components/WeeklyView.tsx + + Replace mock data with dynamic fetching from real calendar sources: + + 1. Remove hardcoded mock events from useEffect that populates calendarEvents + 2. Implement proper API call to fetch real calendar events from connected calendars + 3. Add loading states and proper error handling + 4. Ensure events are properly formatted and styled according to their provider + 5. Add loading indicators while fetching events + 6. Implement fallbacks for failed API calls + + The implementation should: + - Fetch calendar events from the appropriate API libraries + - Dynamically populate the calendarEvents state with real data + - Display events correctly with provider-specific styling + - Handle loading and error states gracefully + + Verify WeeklyView component fetches and displays actual calendar events from connected calendars instead of mock data + WeeklyView component displays real calendar events from connected calendars + + + +## Verification + +After completing these tasks, the following checks should pass: +- Calendar events are fetched from real calendar APIs instead of using mocked data +- WeeklyView component displays actual calendar events instead of mock data +- Bidirectional sync performs real operations instead of just logging to console +- All calendar API integration functions properly interact with their respective services +- Proper error handling is implemented for API failures + +## Success Criteria + +All gaps identified in the VERIFICATION.md for calendar event fetching and sync implementations are resolved: +- Calendar events are fetched from real APIs instead of mock data +- WeeklyView component displays real calendar events +- Bidirectional sync performs actual database/calendar API operations +- All calendar API integrations work with real services \ No newline at end of file diff --git a/.planning/phases/03-calendar-integration/03-06-PLAN.md b/.planning/phases/03-calendar-integration/03-06-PLAN.md new file mode 100644 index 0000000..911127f --- /dev/null +++ b/.planning/phases/03-calendar-integration/03-06-PLAN.md @@ -0,0 +1,162 @@ +--- +phase: 03-calendar-integration +plan: 06 +type: execute +wave: 1 +depends_on: [] +files_modified: + - src/components/CalendarSettings.tsx + - src/app/api/calendar/google/oauth/route.ts + - src/app/api/calendar/apple/oauth/route.ts +autonomous: true +gap_closure: true + +must_haves: + truths: + - "User can connect their Google Calendar account" + - "User can connect their Apple Calendar account" + - "User can view calendar events alongside tasks in weekly view" + - "User can manage calendar connection settings from the application" + - "User's tasks and calendar events are synchronized bidirectionally" + artifacts: + - path: "src/components/CalendarSettings.tsx" + provides: "Functional calendar connection UI with real OAuth triggers" + - path: "src/app/api/calendar/google/oauth/route.ts" + provides: "OAuth callback that properly saves connections" + - path: "src/app/api/calendar/apple/oauth/route.ts" + provides: "OAuth callback that properly saves connections" + key_links: + - from: "src/components/CalendarSettings.tsx" + to: "src/app/api/calendar/google/oauth/route.ts" + via: "connecting Google Calendar via OAuth flow" + pattern: "connect.*google" + - from: "src/components/CalendarSettings.tsx" + to: "src/app/api/calendar/apple/oauth/route.ts" + via: "connecting Apple Calendar via OAuth flow" + pattern: "connect.*apple" + - from: "src/components/CalendarSettings.tsx" + to: "src/app/api/calendar/sync/route.ts" + via: "triggering sync operations" + pattern: "sync.*api" +--- + +# Gap Closure: Calendar Connection UI and Management + +## Objective +Enable functional calendar connection management UI that triggers real OAuth flows and manages connections properly. + +## Purpose +Allow users to successfully connect, disconnect, and manage their calendar connections through the UI. + +## Output +Fully functional CalendarSettings UI component with real OAuth triggers and connection management. + +## Tasks + + + Implement Real Google Calendar OAuth Trigger + src/components/CalendarSettings.tsx + + Enable the Google connection button to trigger actual OAuth flow: + + 1. Replace placeholder button functionality with actual redirect to Google OAuth authorization URL + 2. Implement proper URL construction with client ID, redirect URI, scopes, and state parameters + 3. Ensure proper error handling if OAuth initiation fails + 4. Add loading states for OAuth redirection + 5. Add proper accessibility attributes for screen readers + + The implementation should: + - Construct proper Google OAuth authorization URL + - Redirect user to Google OAuth flow when clicked + - Include necessary OAuth parameters (client_id, redirect_uri, scope, state) + - Preserve user session during OAuth flow + + Clicking "Connect Google Calendar" button redirects to actual Google OAuth page + Google Calendar connection button triggers real OAuth flow to Google + + + + Implement Real Apple Calendar OAuth Trigger + src/components/CalendarSettings.tsx + + Enable the Apple connection button to trigger actual OAuth flow: + + 1. Replace placeholder button functionality with actual redirect to Apple OAuth authorization URL + 2. Implement proper URL construction with client ID, redirect URI, scopes, and state parameters + 3. Ensure proper error handling if OAuth initiation fails + 4. Add loading states for OAuth redirection + 5. Add proper accessibility attributes for screen readers + + The implementation should: + - Construct proper Apple OAuth authorization URL + - Redirect user to Apple OAuth flow when clicked + - Include necessary OAuth parameters (client_id, redirect_uri, scope, state) + - Preserve user session during OAuth flow + + Clicking "Connect Apple Calendar" button redirects to actual Apple OAuth page + Apple Calendar connection button triggers real OAuth flow to Apple + + + + Implement Calendar Disconnection Functionality + src/components/CalendarSettings.tsx + + Enable proper disconnection of calendar accounts: + + 1. Implement actual database removal of CalendarConnection records when disconnected + 2. Add confirmation dialogs for disconnection actions + 3. Ensure tokens are properly removed from database (both access and refresh tokens) + 4. Handle errors that might occur during disconnection + 5. Add loading states during disconnection process + 6. Update UI to reflect successful disconnection immediately + + The implementation should: + - Make API call to remove calendar connection from database + - Display confirmation before removing connection + - Handle API errors gracefully + - Update component state to reflect disconnection + + Clicking "Disconnect" button removes calendar connection from database and UI + Calendar connection disconnection works with proper database removal + + + + Implement Manual Sync Triggering + src/components/CalendarSettings.tsx + + Enable proper manual sync triggering from the UI: + + 1. Implement actual API call to trigger sync when "Sync Now" button is clicked + 2. Ensure sync operation uses correct time range parameters + 3. Add loading states during sync operation + 4. Handle responses from sync endpoint properly + 5. Update last sync time display after successful sync + 6. Show error messages if sync fails + + The implementation should: + - Make API call to /api/calendar/sync endpoint with proper parameters + - Handle sync results and update UI accordingly + - Show loading indicator during sync operation + - Update last sync timestamp display + + Clicking "Sync Now" button triggers actual sync operation and updates last sync time + Manual sync button triggers real sync operation with proper API calls + + + +## Verification + +After completing these tasks, the following checks should pass: +- Clicking "Connect Google Calendar" button redirects to actual Google OAuth page +- Clicking "Connect Apple Calendar" button redirects to actual Apple OAuth page +- Clicking "Disconnect" button removes calendar connection from database +- Clicking "Sync Now" button triggers actual sync operation +- UI properly reflects connection and sync status updates + +## Success Criteria + +All gaps identified in the VERIFICATION.md for calendar connection management UI are resolved: +- Calendar connection buttons trigger real OAuth flows to respective providers +- Calendar disconnection completely removes connections from database +- Manual sync from UI triggers real sync operations +- UI properly reflects connection and sync states \ No newline at end of file