mARTin-B78/My-Weekly-ToDo-List
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(03): create gap closure plans for calendar integration

Browse Source 
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
This commit is contained in:
mARTin 2026-01-25 15:11:32 +01:00
parent 54e8266919
commit 43e5296db4
3 changed files with 504 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

142
.planning/phases/03-calendar-integration/03-04-PLAN.md Normal file
View File

@ -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
<task type="auto">
<name>Fix Google OAuth Callback with Real Token Exchange</name>
<files>src/app/api/calendar/google/oauth/route.ts</files>
<action>
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
</action>
<verify>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</verify>
<done>Google OAuth callback endpoint exchanges real tokens and stores them in database</done>
</task>
<task type="auto">
<name>Fix Apple OAuth Callback with Real Token Exchange</name>
<files>src/app/api/calendar/apple/oauth/route.ts</files>
<action>
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
</action>
<verify>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</verify>
<done>Apple OAuth callback endpoint exchanges real tokens and stores them in database</done>
</task>
<task type="auto">
<name>Implement Database Storage for OAuth Tokens</name>
<files>prisma/schema.prisma</files>
<action>
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
</action>
<verify>Check that prisma/schema.prisma defines CalendarConnection model with userId, provider, accessToken, refreshToken, expiresAt fields</verify>
<done>CalendarConnection model properly defined with all required fields for OAuth token storage</done>
</task>
</tasks>
## 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

200
.planning/phases/03-calendar-integration/03-05-PLAN.md Normal file
View File

@ -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
<task type="auto">
<name>Fix Calendar Events Fetching to Use Real APIs</name>
<files>src/lib/calendar-events.ts</files>
<action>
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
</action>
<verify>Run `npm test` for calendar events utility and verify it can fetch real events instead of returning mock data</verify>
<done>Calendar events utility fetches real events from connected calendars</done>
</task>
<task type="auto">
<name>Complete Google Calendar API Integration</name>
<files>src/lib/google-calendar.ts</files>
<action>
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
</action>
<verify>Run `npm test` for google-calendar.ts and verify all functions properly interact with Google Calendar API</verify>
<done>Google Calendar API integration functions work with real Google Calendar API calls</done>
</task>
<task type="auto">
<name>Complete Apple Calendar API Integration</name>
<files>src/lib/apple-calendar.ts</files>
<action>
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
</action>
<verify>Run `npm test` for apple-calendar.ts and verify all functions properly interact with Apple Calendar API</verify>
<done>Apple Calendar API integration functions work with real Apple Calendar API calls</done>
</task>
<task type="auto">
<name>Complete Bidirectional Sync Implementation</name>
<files>src/lib/calendar-sync.ts</files>
<action>
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
</action>
<verify>Run `npm test` for calendar-sync.ts and verify it performs actual operations instead of just console logging</verify>
<done>Bidirectional sync performs actual database/calendar API operations</done>
</task>
<task type="auto">
<name>Update Weekly View to Display Real Calendar Events</name>
<files>src/components/WeeklyView.tsx</files>
<action>
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
</action>
<verify>Verify WeeklyView component fetches and displays actual calendar events from connected calendars instead of mock data</verify>
<done>WeeklyView component displays real calendar events from connected calendars</done>
</task>
</tasks>
## 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

162
.planning/phases/03-calendar-integration/03-06-PLAN.md Normal file
View File

@ -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
<task type="auto">
<name>Implement Real Google Calendar OAuth Trigger</name>
<files>src/components/CalendarSettings.tsx</files>
<action>
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
</action>
<verify>Clicking "Connect Google Calendar" button redirects to actual Google OAuth page</verify>
<done>Google Calendar connection button triggers real OAuth flow to Google</done>
</task>
<task type="auto">
<name>Implement Real Apple Calendar OAuth Trigger</name>
<files>src/components/CalendarSettings.tsx</files>
<action>
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
</action>
<verify>Clicking "Connect Apple Calendar" button redirects to actual Apple OAuth page</verify>
<done>Apple Calendar connection button triggers real OAuth flow to Apple</done>
</task>
<task type="auto">
<name>Implement Calendar Disconnection Functionality</name>
<files>src/components/CalendarSettings.tsx</files>
<action>
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
</action>
<verify>Clicking "Disconnect" button removes calendar connection from database and UI</verify>
<done>Calendar connection disconnection works with proper database removal</done>
</task>
<task type="auto">
<name>Implement Manual Sync Triggering</name>
<files>src/components/CalendarSettings.tsx</files>
<action>
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
</action>
<verify>Clicking "Sync Now" button triggers actual sync operation and updates last sync time</verify>
<done>Manual sync button triggers real sync operation with proper API calls</done>
</task>
</tasks>
## 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