New Integration: ClickUp

Description

Add ClickUp integration to sync tasks, spaces, lists, goals, and project activity into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/linear/ - Similar project management system
• integrations/github/ - Similar issue/task tracking
• integrations/slack/ - For messaging reference

Required Files Structure

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

ClickUp API Integration

OAuth Setup

• Use OAuth 2.0 (Authorization Code Grant)
• Authorization URL: https://app.clickup.com/api?client_id={client_id}&redirect_uri={redirect_uri}
• Token URL: POST https://api.clickup.com/api/v2/oauth/token
• Only Workspace owners or admins can create OAuth apps
• Users select which Workspaces to grant access during authorization
• Required parameters: client_id, client_secret, code

Base URL

• https://api.clickup.com/api/v2

Key Endpoints

• GET /api/v2/team - Get authorized teams/workspaces
• GET /api/v2/team/{team_id}/space - Get spaces in a workspace
• POST /api/v2/team/{team_id}/space - Create a space
• GET /api/v2/space/{space_id} - Get space details
• GET /api/v2/space/{space_id}/folder - Get folders in a space
• GET /api/v2/folder/{folder_id}/list - Get lists in a folder
• GET /api/v2/list/{list_id} - Get list details
• GET /api/v2/list/{list_id}/task - Get tasks in a list
• POST /api/v2/list/{list_id}/task - Create a task
• GET /api/v2/task/{task_id} - Get task details
• PUT /api/v2/task/{task_id} - Update a task
• DELETE /api/v2/task/{task_id} - Delete a task
• GET /api/v2/task/{task_id}/comment - Get task comments
• POST /api/v2/task/{task_id}/comment - Add a comment
• GET /api/v2/task/{task_id}/member - Get task members
• GET /api/v2/list/{list_id}/member - Get list members
• GET /api/v2/team/{team_id}/goal - Get goals
• GET /api/v2/goal/{goal_id} - Get goal details
• GET /api/v2/team/{team_id}/time_entries - Get time entries
• POST /api/v2/team/{team_id}/webhook - Create a webhook
• GET /api/v2/team/{team_id}/webhook - Get webhooks

Events to Track

1. Task Events

   • Task created
   • Task updated (status, assignee, priority, due date)
   • Task completed
   • Task deleted
   • Task moved between lists

2. Comment Events

   • Comment added to task
   • Comment updated
   • Comment deleted

3. List/Space Events

   • List created/updated/deleted
   • Space created/updated/deleted
   • Folder created/updated/deleted

4. Goal Events

   • Goal created
   • Goal updated
   • Key result updated

5. Time Tracking Events

   • Time entry created
   • Time entry updated
   • Time entry deleted

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.0 flow in account-create.ts
• Create ClickUp API utilities in utils.ts
• Implement sync logic in schedule.ts for tasks, spaces, and lists
• Set up webhook ingestion for real-time task and comment events
• Convert ClickUp events to CORE activity format
• Handle workspace hierarchy (Team > Space > Folder > List > Task)
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• ClickUp API v2 uses "Team" where v3 uses "Workspace" - use v2 terminology for consistency
• OAuth tokens don't expire but can be revoked
• Webhooks are created per workspace and support filtering by space/folder/list
• The API hierarchy is: Workspace (Team) > Space > Folder > List > Task
• Personal API tokens also supported for testing
• Webhook events include: taskCreated, taskUpdated, taskDeleted, taskStatusUpdated, taskAssigneeUpdated, taskCommentPosted, listCreated, folderCreated, goalCreated, etc.

Resources

• ClickUp Developer Portal
• ClickUp API Getting Started
• ClickUp Authentication Docs
• ClickUp API v2/v3 Terminology
• ClickUp OpenAPI Spec

Labels

enhancement, integration, new-feature

Start by comparing integrations/linear/ and integrations/github/src/index.ts, then map the required integrations/clickup/ files and the ClickUp OAuth and hierarchy requirements. Done means the integration structure, OAuth flow, task/space/list sync, webhook ingestion, activity conversion, error handling, documentation, and integrations/README.md entry are implemented.