JustJoinTheMeeting

A macOS application that automatically monitors your calendar for upcoming Zoom meetings and offers to join them automatically when they start.

Features

• Calendar Integration: Monitors all your calendars for upcoming meetings
• Smart Detection: Intelligently extracts Zoom URLs from event locations, notes, and URL fields
• User Consent: Always asks permission before auto-joining meetings
• Precise Timing: Joins meetings exactly at start time
• Background Monitoring: Continuously polls calendar every minute for new meetings

Architecture

Core Components

1. Calendar Access & Permissions

   • Uses EventKit to access Calendar and Reminder data
   • Requests proper permissions on first run
   • Requires user authorization for both Events and Reminders

2. Event Polling System

   • Polls calendar every 60 seconds for upcoming meetings
   • Looks ahead 15 minutes to catch meetings that are about to start
   • Maintains a processed events cache to avoid duplicate prompts

3. Zoom URL Detection

   • Multi-stage URL extraction from:
     • Event location field
     • Event notes/description
     • Event URL field (if available)
   • Uses sophisticated regex patterns to identify Zoom meeting URLs
   • Supports various Zoom URL formats (zoom.us, company.zoom.us, etc.)

4. User Interface

   • Native macOS alert dialogs for meeting join prompts
   • Shows meeting title and asks for auto-join permission
   • Handles user responses and schedules auto-join accordingly

5. Auto-Join Scheduler

   • Calculates precise time until meeting start
   • Uses DispatchQueue to schedule URL opening at exact start time
   • Opens Zoom URLs using NSWorkspace.shared.open()

Code Structure

Sources/JustJoinTheMeeting/
└── main.swift              # Complete application logic

The application follows a functional approach with these key functions:

• requestAccess(): Handles Calendar/Reminder permission requests
• startPolling(): Begins the calendar monitoring loop
• checkForUpcomingMeetings(): Core polling logic that scans for events
• extractZoomURL(): Intelligent Zoom URL extraction
• promptToJoin(): User consent dialog management
• scheduleAutoJoin(): Precise meeting join scheduling

Requirements

• macOS 13.0+: Required for the Swift runtime and EventKit APIs
• Calendar Access: User must grant permission to access Calendar data
• Zoom Client: Zoom application must be installed for URLs to open properly

Installation & Setup

1. Clone the repository:

   git clone <repository-url>
   cd JustJoinTheMeeting

2. Build the application:

   swift build

3. Run the application:

   .build/debug/JustJoinTheMeeting

4. Grant Permissions:

   • The app will prompt for Calendar and Reminder access on first run
   • These permissions are required for the app to function

Usage

1. Start the Application: Run the built executable
2. Grant Permissions: Allow access to Calendar and Reminders when prompted
3. Background Monitoring: The app runs in the background, checking every minute
4. Meeting Detection: When a Zoom meeting is found within 15 minutes, you'll see a dialog
5. Auto-Join Decision: Choose "Yes, Auto-Join" to automatically join at start time
6. Automatic Opening: At meeting start time, Zoom will open with the meeting URL

Debugging & Logs

The application provides extensive logging to help debug issues:

• Timestamp: All log messages include ISO8601 timestamps
• Event Details: Logs show found events, calendars, and time ranges
• URL Extraction: Details about Zoom URL detection process
• User Interactions: Records of dialog responses and auto-join decisions
• Timing Information: Shows seconds until meeting start and scheduling details

Example log output:

[2024-04-29T16:30:45Z] Starting polling
[2024-04-29T16:30:45Z] Checking for upcoming meetings
[2024-04-29T16:30:45Z] Found 3 calendars
[2024-04-29T16:30:45Z] Found 1 events in the time range
[2024-04-29T16:30:45Z] Checking event: Weekly Team Meeting
[2024-04-29T16:30:45Z] Found Zoom URL in notes: https://zoom.us/j/123456789

Troubleshooting

Common Issues

1. No meetings detected:

   • Verify Calendar permissions are granted
   • Check that Zoom URLs are present in event location, notes, or URL fields
   • Ensure meetings are within the next 15 minutes

2. URL not detected:

   • The app looks for URLs containing "zoom" in various fields
   • Supported patterns: https://zoom.us/j/..., https://company.zoom.us/j/...
   • Check that the URL format matches expected patterns

3. Permissions issues:

   • Go to System Preferences > Security & Privacy > Privacy
   • Ensure the app has access to Calendar and Reminders
   • Re-run the app if permissions were recently granted

4. App not running in background:

   • The app must stay running to monitor calendar
   • Consider running from Terminal to see log output
   • Use nohup for true background execution

Debug Mode

For detailed debugging, run from Terminal to see all log output:

.build/debug/JustJoinTheMeeting

Development

Building for Release

swift build -c release

Development Environment

The project includes VSCode configuration in .vscode/launch.json for debugging with the Swift extension.

Code Improvements Made

Recent fixes applied to resolve functionality issues:

1. Fixed time range bug: Changed from 60-minute to 15-minute lookahead window
2. Improved URL extraction: Enhanced regex patterns for better Zoom URL detection
3. Fixed optional handling: Properly handle optional eventIdentifier values
4. Added immediate join: Handle meetings that have already started
5. Enhanced logging: More detailed debug information throughout the flow

Contributing

Feel free to submit issues and enhancement requests. When contributing:

1. Maintain the existing code style and logging patterns
2. Test with various calendar and Zoom URL formats
3. Ensure proper error handling and user feedback
4. Update documentation for any architectural changes

License

[Add your preferred license here]