diff --git a/.github/workflows/proxmox-deployment.yml b/.github/workflows/proxmox-deployment.yml new file mode 100644 index 0000000..adcb19c --- /dev/null +++ b/.github/workflows/proxmox-deployment.yml @@ -0,0 +1,38 @@ +name: Proxmox Deployment + +on: + push: + create: + delete: + +jobs: + setup-runner: + runs-on: ubuntu-latest + steps: + - name: Install dependencies + run: | + sudo apt-get update + sudo apt install -y sshpass jq + - name: Setting up runner + uses: maxklema/proxmox-launchpad@main + with: + proxmox_username: ${{ secrets.PROXMOX_USERNAME }} + proxmox_password: ${{ secrets.PROXMOX_PASSWORD }} + github_pat: ${{ secrets.RUNNER_PAT }} + deploy: + runs-on: self-hosted + needs: setup-runner + steps: + - name: Deploy to Proxmox + uses: maxklema/proxmox-launchpad@main + with: + proxmox_username: ${{ secrets.PROXMOX_USERNAME }} + proxmox_password: ${{ secrets.PROXMOX_PASSWORD }} + public_key: ${{ secrets.PUBLIC_KEY }} + http_port: 3000 + install_command: npm install + start_command: meteor run --port 0.0.0.0:3000 --allow-superuser + runtime_language: nodejs + services: '["meteor"]' + + \ No newline at end of file diff --git a/.gitignore b/.gitignore index 12ac647..85e62b7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,6 @@ node_modules/ -.DS_Store \ No newline at end of file +.DS_Store + +# Settings files (keep example, ignore actual settings) +settings.json +settings-local.json \ No newline at end of file diff --git a/.meteor/packages b/.meteor/packages index 044a30e..6e10e98 100644 --- a/.meteor/packages +++ b/.meteor/packages @@ -25,3 +25,4 @@ hot-module-replacement@0.5.4 # Update code in development without reloading the blaze-hot # Update files using Blaze's API with HMR accounts-base accounts-password +webapp # HTTP server for webhooks and OAuth callbacks diff --git a/README.md b/README.md index e7fba3d..019d02a 100644 --- a/README.md +++ b/README.md @@ -43,10 +43,11 @@ Quick start: [click here](./HOW_TO_USE.md) 1. **Clock In/Clock Out:** Simple, intuitive interface for starting and ending work or project sessions 2. **Project & Objective Allocation:** Tag time entries to specific projects, objectives, or tasks (e.g., "robotics build," "grant writing," "classwork") 3. **Personal Reflection & Notes:** Add context, challenges, and accomplishments to each time entry, helping communicate value and obstacles -4. **User-Controlled Sharing:** All data remains private by default. Share with others (leaders, sponsors, teachers) only with explicit approval -5. **Role Flexibility:** Designed for employees, students, mentors, volunteers, and nonprofit contributors -6. **Reporting & Summaries:** Generate reports or summaries to share contributions, progress, or challenges as needed -7. **Coach/Assistant Persona:** Supportive tool that helps with personal growth and positive communication +4. **Calendar Integration:** Connect Google Calendar or Microsoft Outlook to automatically suggest time entries based on your meetings and appointments +5. **User-Controlled Sharing:** All data remains private by default. Share with others (leaders, sponsors, teachers) only with explicit approval +6. **Role Flexibility:** Designed for employees, students, mentors, volunteers, and nonprofit contributors +7. **Reporting & Summaries:** Generate reports or summaries to share contributions, progress, or challenges as needed +8. **Coach/Assistant Persona:** Supportive tool that helps with personal growth and positive communication --- @@ -118,6 +119,8 @@ Quick start: [click here](./HOW_TO_USE.md) - **Start a Personal Session:** Begin tracking your work, study, or project time with simple clock in/out - **Tag Your Activities:** Create projects or tasks to categorize your time (e.g., "Math Homework," "Robot Assembly," "Grant Writing") - **Add Reflections:** Include notes about challenges, accomplishments, or context for each session +- **Connect Your Calendar:** Link Google Calendar or Microsoft Outlook to automatically suggest time entries from your meetings +- **Review Calendar Events:** Confirm, adjust, or dismiss suggested time entries from your calendar events - **Control Your Privacy:** All data stays private unless you choose to share specific summaries or reports - **Generate Reports:** Create summaries to share with mentors, teachers, or supervisors when beneficial diff --git a/calendar.md b/calendar.md new file mode 100644 index 0000000..fc989ce --- /dev/null +++ b/calendar.md @@ -0,0 +1,210 @@ +# Calendar Integration Documentation + +TimeHarbor supports integration with external calendar services to help users automatically suggest time entries based on their scheduled meetings and appointments. + +## Supported Calendar Providers + +### Google Calendar +- **Module**: googleapis +- **Authentication**: OAuth 2.0 +- **API**: Google Calendar API v3 +- **Permissions Required**: `https://www.googleapis.com/auth/calendar.readonly` + +### Microsoft Outlook/Office 365 +- **Module**: @microsoft/microsoft-graph-client +- **Authentication**: OAuth 2.0 +- **API**: Microsoft Graph API +- **Permissions Required**: `https://graph.microsoft.com/calendars.read` + +## OAuth Setup and Configuration + +### Google Calendar Setup +1. Create a Google Cloud Project at https://console.cloud.google.com/ +2. Enable the Google Calendar API +3. Create OAuth 2.0 credentials (Web application) +4. Add authorized redirect URIs: + - `http://localhost:3000/auth/google/callback` (development) + - `https://yourdomain.com/auth/google/callback` (production) +5. Set environment variables: + ``` + GOOGLE_CLIENT_ID=your_client_id + GOOGLE_CLIENT_SECRET=your_client_secret + ``` + +### Microsoft Graph Setup +1. Register an application in Azure Active Directory +2. Configure API permissions for Microsoft Graph: + - Calendars.Read (delegated permission) +3. Add redirect URIs: + - `http://localhost:3000/auth/microsoft/callback` (development) + - `https://yourdomain.com/auth/microsoft/callback` (production) +4. Set environment variables: + ``` + MICROSOFT_CLIENT_ID=your_client_id + MICROSOFT_CLIENT_SECRET=your_client_secret + ``` + +## Data Access and Privacy + +### What Data is Accessed +- **Event Title**: For display and time entry suggestions +- **Event Start/End Time**: To calculate duration and suggest logged time +- **Event Status**: To filter out cancelled events +- **Attendee Status**: To confirm user attendance (optional) + +### What Data is NOT Accessed +- Event descriptions or detailed content +- Private event details beyond title +- Attendee email addresses or personal information +- Event locations (unless needed for time entry context) + +### Data Storage Policy +- **OAuth Tokens**: Encrypted and stored securely in user profiles +- **Calendar Events**: Temporarily cached for suggestion purposes only +- **Event Details**: Minimal data stored, only what's necessary for time logging +- **Retention**: Calendar data is not permanently stored; refreshed on each login + +### User Control +- Users can connect/disconnect calendar services at any time +- Individual events can be dismissed permanently +- No automatic time logging without explicit user confirmation +- Users control which events are suggested based on their attendance + +## How Calendar Integration Works + +### Event Fetching +1. **On Login**: Fetch events from the past 7 days and next 7 days +2. **Real-time Updates**: Optional webhook notifications for new/updated events +3. **Manual Refresh**: Users can manually refresh calendar events + +### Event Filtering +- Only events where the user is an attendee +- Exclude all-day events +- Exclude events marked as "free" or "out of office" +- Exclude cancelled events +- Only events longer than 15 minutes + +### Time Suggestion Logic +- Suggest the full duration of the meeting for logging +- Allow users to adjust the time before confirming +- Pre-fill project/team if event title matches existing projects +- Suggest activity title based on event title + +### Event Confirmation Workflow +1. Display list of unlogged calendar events +2. Show event title, time, duration, and suggested log time +3. Allow user to: + - Confirm and log with suggested time + - Adjust time before logging + - Dismiss event (won't show again) + - Snooze event (show again later) + +## Security Considerations + +### OAuth Token Security +- Tokens are encrypted before database storage +- Refresh tokens are rotated regularly +- Access tokens have limited scope and lifetime +- Tokens are never logged or exposed in client-side code + +### API Rate Limiting +- Implement exponential backoff for API requests +- Cache responses to minimize API calls +- Respect provider rate limits and quotas + +### Error Handling +- Graceful degradation when calendar services are unavailable +- Clear error messages for authentication failures +- Automatic token refresh handling + +## Webhook Support (Optional Enhancement) + +### Google Calendar Webhooks +- Use Google Calendar Push Notifications +- Set up webhook endpoint: `/webhooks/google/calendar` +- Verify webhook signatures for security +- Handle event notifications in real-time + +### Microsoft Graph Webhooks +- Use Microsoft Graph subscriptions +- Set up webhook endpoint: `/webhooks/microsoft/calendar` +- Implement subscription renewal logic +- Handle event change notifications + +## User Interface + +### Calendar Connection Settings +- Located in user profile or main navigation +- Simple connect/disconnect buttons for each provider +- Display connection status and last sync time +- Option to refresh calendar data manually + +### Event Confirmation Interface +- Dedicated section on home page or separate calendar page +- List of pending calendar events +- Quick action buttons for each event +- Batch actions for multiple events + +## Installation and Dependencies + +### Required NPM Packages +```bash +npm install googleapis @microsoft/microsoft-graph-client +``` + +### Environment Configuration +```javascript +// In settings.json or environment variables +{ + "google": { + "clientId": "your_google_client_id", + "clientSecret": "your_google_client_secret" + }, + "microsoft": { + "clientId": "your_microsoft_client_id", + "clientSecret": "your_microsoft_client_secret" + } +} +``` + +## API Methods + +### Client Methods +- `connectGoogleCalendar()` - Initiate Google OAuth flow +- `connectMicrosoftCalendar()` - Initiate Microsoft OAuth flow +- `disconnectCalendar(provider)` - Remove calendar connection +- `refreshCalendarEvents()` - Manually refresh events +- `confirmCalendarEvent(eventId, timeData)` - Confirm and log event +- `dismissCalendarEvent(eventId)` - Dismiss event permanently + +### Server Methods +- `calendar.fetchEvents(provider, dateRange)` - Fetch events from calendar API +- `calendar.storeTokens(provider, tokens)` - Securely store OAuth tokens +- `calendar.createTimeEntry(eventData)` - Create time entry from calendar event +- `calendar.handleWebhook(provider, payload)` - Process webhook notifications + +## Privacy Statement for Users + +TimeHarbor's calendar integration is designed with your privacy in mind: + +- **Read-Only Access**: We only read your calendar data; we never modify or create events +- **Minimal Data**: We only access event titles, times, and your attendance status +- **No Permanent Storage**: Calendar events are not permanently stored in our database +- **User Control**: You decide which events to log and can disconnect your calendar at any time +- **Secure Storage**: Any temporary data is encrypted and secured +- **No Sharing**: Your calendar data is never shared with third parties + +## Troubleshooting + +### Common Issues +1. **OAuth Authorization Errors**: Check client ID and redirect URI configuration +2. **API Rate Limits**: Implement exponential backoff and caching +3. **Token Expiration**: Ensure proper refresh token handling +4. **Webhook Failures**: Verify webhook URL accessibility and signature validation + +### Support +For calendar integration issues, check: +1. Environment variable configuration +2. OAuth application settings in provider console +3. Network connectivity to calendar APIs +4. Server logs for detailed error messages \ No newline at end of file diff --git a/client/main.html b/client/main.html index e80a6ac..82c10c6 100644 --- a/client/main.html +++ b/client/main.html @@ -23,6 +23,7 @@

TimeHarbor

Home Teams Projects + Calendar {{#if currentUser}}