New Integration: Excalidraw

Description

Add Excalidraw integration to sync whiteboard drawings, collaborative sessions, and diagram updates into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/notion/ - Similar document/content system
• integrations/google-docs/ - Document management integration
• integrations/slack/ - For reference

Required Files Structure

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

Excalidraw API Integration

Authentication Setup

• Use Excalidraw+ API token authentication for cloud-hosted instances
• Self-hosted instances may use custom auth mechanisms
• The @excalidraw/excalidraw npm package provides the React component API

Key APIs

• ExcalidrawAPI - Core API accessed via excalidrawAPI prop
  • updateScene(sceneData) - Update drawings programmatically
  • getSceneElements() - Retrieve current scene elements
  • getFiles() - Get binary files (images) in the scene
  • exportToBlob() - Export drawing as image blob
  • exportToSvg() - Export drawing as SVG
• Collaboration API - Real-time collaboration endpoints
  • WebSocket-based real-time sync
  • Room management for shared drawings
• REST API (Excalidraw+) - Cloud platform endpoints
  • Scene CRUD operations
  • Team/workspace management
  • File storage and retrieval

Events to Track

1. Drawing Activity - New drawings created, existing drawings modified, drawings deleted
2. Collaboration - Users joining/leaving shared sessions, real-time edits
3. Export Events - Drawings exported to PNG, SVG, or other formats
4. Library Updates - Custom shape libraries added or modified

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement Excalidraw+ token authentication flow in account-create.ts
• Create API utilities in utils.ts
• Implement sync logic in schedule.ts for drawings and collaboration events
• Convert drawing events to CORE activity format
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Excalidraw is open-source; self-hosted instances can use Docker deployment
• The React component (@excalidraw/excalidraw) does not support SSR - must be client-side rendered
• Drawings are stored as JSON scene data with element arrays
• Binary files (images) are stored separately and referenced by ID
• Used by VSCode, Obsidian, Notion, CodeSandbox, and Google Cloud

Resources

• Excalidraw Developer Docs
• Excalidraw API Reference
• ExcalidrawAPI Props
• Integration Guide
• Utils Documentation

Labels

enhancement, integration, new-feature