New Integration: Box

Description

Add Box integration to sync cloud storage data including files, folders, collaborations, comments, and metadata into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/google-docs/ - Similar document/cloud storage system
• integrations/notion/ - Content management integration
• integrations/slack/ - For reference

Required Files Structure

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

Box API Integration

OAuth Setup

• Supports OAuth 2.0, JSON Web Token (JWT), Client Credentials, and App Token authentication
• OAuth 2.0 recommended for user-facing integrations
• Developer Console available for app management
• Base URL: https://api.box.com/2.0
• Developer docs: https://developer.box.com/

Key Endpoints

• GET /files/{id} - Get file info
• GET /folders/{id} - Get folder info
• GET /folders/{id}/items - List folder items
• POST /files/content - Upload file
• GET /files/{id}/comments - Get file comments
• GET /collaborations - List collaborations
• GET /events - Get user/enterprise events
• GET /search - Search content
• GET /metadata_templates - Get metadata templates
• GET /users - List users

Events to Track

1. Files - File uploaded, downloaded, previewed, shared, moved, deleted, versioned
2. Folders - Folder created, renamed, moved, shared, deleted
3. Collaborations - Collaborator added, removed, role changed
4. Comments - Comment added, edited, deleted on files
5. Metadata - Metadata applied, updated, 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 Box Platform API calls
• Implement sync logic in schedule.ts for files, folders, and events
• Convert file/folder events to CORE activity format
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Multiple authentication methods available (OAuth 2.0, JWT, Client Credentials, App Token)
• Box Events API provides enterprise-wide event stream for audit and sync
• SDKs available for multiple languages
• Box CLI available for scripting and automation
• Box UI Elements available for embedded experiences
• Legal holds and retention policies supported for compliance use cases

Resources

• Box Developer Documentation
• Box API Reference
• Box Platform
• Box Postman Collection

Labels

enhancement, integration, new-feature

Start by reading the templates in integrations/google-docs/, integrations/notion/, integrations/slack/, and the integrations/github/src/index.ts pattern. Review the Box API documentation and define the OAuth, sync, activity, error-handling, and rate-limiting scope across the listed files. Done means the Box structure, authentication, synchronization, activity conversion, documentation, and integrations/README.md entry are complete.