New Integration: Miro

Description

Add Miro integration to sync visual collaboration data including boards, items, comments, tags, and team activity into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/notion/ - Similar collaboration/content system
• integrations/linear/ - Project management integration
• integrations/slack/ - For reference

Required Files Structure

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

Miro API Integration

OAuth Setup

• Use OAuth 2.0 authorization code flow
• RESTful API with predictable, resource-oriented URLs
• Standard HTTP response codes for error reporting
• Base URL: https://api.miro.com/v2
• Developer docs: https://developers.miro.com/

Key Endpoints

• GET /boards - List boards
• GET /boards/{board_id} - Get board details
• GET /boards/{board_id}/items - List board items
• POST /boards/{board_id}/sticky_notes - Create sticky note
• POST /boards/{board_id}/cards - Create card
• POST /boards/{board_id}/shapes - Create shape
• POST /boards/{board_id}/connectors - Create connector
• GET /boards/{board_id}/tags - List tags
• GET /boards/{board_id}/members - List board members
• POST /webhooks/board_subscriptions - Subscribe to board webhooks

Events to Track

1. Boards - Board created, updated, shared, archived, deleted
2. Items - Sticky note created, card added, shape drawn, text edited, item moved
3. Collaboration - Member added, member removed, comment posted
4. Webhooks - Real-time board and item notifications (new in v2)
5. Tags - Tag created, applied, removed

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.0 flow in account-create.ts
• Create API utilities in utils.ts for Miro REST API v2 calls
• Implement sync logic in schedule.ts for boards, items, and members
• Convert board events to CORE activity format
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• V2 API replaced polymorphic Widget API with specific endpoints per item type (sticky notes, cards, shapes, etc.)
• Webhooks introduced in v2 (not available in v1) for board and item notifications
• V1 to V2 migration guide available for reference
• Interactive API playground available in documentation
• Consider using webhooks for real-time sync rather than polling

Resources

• Miro Developer Platform
• REST API Reference Guide
• Miro REST API Introduction
• Getting Started with OAuth
• REST API Quickstart

Labels

enhancement, integration, new-feature