New Integration: Monday

Description

Add Monday.com integration to sync boards, items, updates, and work activity into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/linear/ - Similar project management integration
• integrations/todoist/ - Task management integration
• integrations/github/ - For webhook and event patterns

Required Files Structure

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

Monday.com API Integration

OAuth Setup

• Use OAuth 2.0 for authorization
• Access token sent in Authorization header
• API endpoint: https://api.monday.com/v2
• API is built on GraphQL (single endpoint for all operations)

Key Queries/Mutations (GraphQL)

• boards - List and query boards
• items - List and manage items (tasks)
• updates - Get updates/comments on items
• users - List workspace users
• groups - Board groups/sections
• columns - Board column definitions
• workspaces - List workspaces
• create_item - Create new items
• change_column_value - Update item column values
• create_update - Add comments/updates to items

API Architecture

• GraphQL-based (not REST) - single endpoint for all operations
• Provides flexibility for querying exactly the data needed
• API playground available for testing queries

Events to Track

1. Items - Item created, updated, status changed, moved, deleted
2. Boards - Board created, updated, archived
3. Updates - Comments/updates posted on items
4. Groups - Groups created, items moved between groups
5. Status Changes - Column value changes (especially status columns)
6. Assignments - People column changes (task assignments)

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.0 flow in account-create.ts
• Create GraphQL query utilities in utils.ts (note: Monday uses GraphQL, not REST)
• Implement sync logic in schedule.ts for boards, items, and updates
• Set up webhook handling for real-time item and board updates
• Convert Monday.com events to CORE activity format
• Add error handling and rate limiting (complexity-based limits)
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Monday.com uses GraphQL, not REST -- all requests go to a single endpoint https://api.monday.com/v2
• Rate limiting is complexity-based rather than request-count based
• The API playground at monday.com/developers/v2/try-it-yourself is useful for testing
• Column types are flexible and custom, requiring dynamic handling
• Webhooks are available for real-time notifications on board and item changes

Resources

• Monday.com API Reference
• Getting Started Guide
• Authentication Guide
• API Playground
• Monday.com Apps Framework

Labels

enhancement, integration, new-feature