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

Start by comparing integrations/google-calendar/, integrations/cal_com/, integrations/slack/, and integrations/github/src/index.ts to understand the integration conventions. Review the Clockwise API documentation and define the OAuth flow, sync behavior, activity format, error handling, and rate limiting across the listed files. Done means the new integrations/clockwise/ structure works, documentation is added, and integrations/README.md lists it.