New Integration: Clockwise

Description

Add Clockwise integration to sync calendar optimization data, scheduling preferences, focus time blocks, and meeting analytics into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/google-calendar/ - Similar calendar management system
• integrations/cal_com/ - Scheduling integration
• integrations/slack/ - For reference

Required Files Structure

integrations/clockwise/
├── src/
│   ├── index.ts          # Main entry, OAuth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # Clockwise API utilities
│   ├── account-create.ts # OAuth setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

Clockwise API Integration

Authentication Setup

• Use OAuth 2.0 for user authentication
• API token-based access for server-to-server communication
• Clockwise integrates with Google Calendar and Outlook

Key API Endpoints

• GET /api/v1/user/preferences - Get user scheduling preferences
• GET /api/v1/user/focus-time - Get focus time blocks
• POST /api/v1/events/optimize - Trigger calendar optimization
• GET /api/v1/events/flexible - List flexible meetings
• GET /api/v1/analytics/meetings - Meeting analytics data
• GET /api/v1/analytics/focus-time - Focus time analytics
• POST /api/v1/scheduling-links - Create scheduling links
• GET /api/v1/team/availability - Team availability windows

Events to Track

1. Calendar Optimization - Meetings rescheduled, focus time created, conflicts resolved
2. Focus Time - Focus time blocks created, protected, or interrupted
3. Meeting Analytics - Meeting frequency, duration trends, meeting-free days
4. Scheduling Events - Scheduling link usage, availability checks, team coordination
5. Preferences Changes - Working hours updates, focus time preference changes

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.0 authentication flow in account-create.ts
• Create API utilities in utils.ts
• Implement sync logic in schedule.ts for calendar events, focus time, and analytics
• Convert calendar optimization events to CORE activity format
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Clockwise operates on top of Google Calendar and Outlook - may need to coordinate with existing calendar integrations
• Focus time and flexible meeting concepts are Clockwise-specific features
• The API uses standard REST conventions with JSON responses
• Clockwise has a GitHub organization (clockwisehq) with potential SDK resources
• Successful API calls return HTTP 204 (No Content) for mutation operations

Resources

• Clockwise API Documentation
• Clockwise GitHub
• Clockwise Developer Info

Labels

enhancement, integration, new-feature