New Integration: YouTube

Description

Add YouTube integration to sync channel activity, video metadata, playlists, comments, and analytics into CORE using the YouTube Data API v3.

Reference Implementations

Existing Integrations (use as templates)

• integrations/google-calendar/ - Similar Google OAuth 2.0 pattern
• integrations/google-docs/ - Google API integration reference
• integrations/google-sheets/ - Google API integration reference

Required Files Structure

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

YouTube Data API v3 Integration

OAuth Setup

• Use Google OAuth 2.0 Authorization Code flow
• Authorization URL: https://accounts.google.com/o/oauth2/v2/auth
• Token URL: https://oauth2.googleapis.com/token
• Required scopes:
  • https://www.googleapis.com/auth/youtube.readonly - View YouTube account (channels, playlists, videos)
  • https://www.googleapis.com/auth/youtube - Manage YouTube account
  • https://www.googleapis.com/auth/youtube.force-ssl - View and manage YouTube videos, ratings, comments, captions
  • https://www.googleapis.com/auth/youtube.upload - Upload YouTube videos
  • https://www.googleapis.com/auth/youtube.channel-memberships.creator - View channel memberships
  • https://www.googleapis.com/auth/yt-analytics.readonly - View YouTube Analytics reports (optional)

Key Endpoints

Base URL: https://www.googleapis.com/youtube/v3

Channels

• GET /channels?part=snippet,statistics,contentDetails&mine=true - Get authenticated user's channel
• GET /channels?part=snippet,statistics&id={channelId} - Get channel by ID

Videos

• GET /videos?part=snippet,statistics,contentDetails&id={videoId} - Get video details
• GET /videos?part=snippet,statistics&chart=mostPopular - Get popular videos
• POST /videos?part=snippet,status - Upload a video
• PUT /videos?part=snippet - Update video metadata
• DELETE /videos?id={videoId} - Delete a video

Playlists

• GET /playlists?part=snippet,contentDetails&mine=true - List user's playlists
• GET /playlists?part=snippet&channelId={channelId} - List channel playlists
• GET /playlistItems?part=snippet&playlistId={playlistId} - List playlist items

Search

• GET /search?part=snippet&q={query}&type=video - Search videos
• GET /search?part=snippet&channelId={channelId}&type=video - Search within a channel

Comments

• GET /commentThreads?part=snippet&videoId={videoId} - List comment threads for a video
• GET /comments?part=snippet&parentId={commentId} - List replies to a comment
• POST /commentThreads?part=snippet - Post a top-level comment

Subscriptions

• GET /subscriptions?part=snippet&mine=true - List user's subscriptions

Activities

• GET /activities?part=snippet,contentDetails&mine=true - List channel activities

Captions

• GET /captions?part=snippet&videoId={videoId} - List captions for a video
• GET /captions/{captionId} - Download caption track

Events to Track

1. Videos

   • New video uploaded
   • Video metadata updated (title, description, tags)
   • Video published / unpublished
   • Video statistics changes (views, likes, comments count)

2. Comments

   • New comment on video
   • Comment reply received
   • Comment moderation actions

3. Playlists

   • Playlist created / updated
   • Video added to / removed from playlist

4. Channel Activity

   • New subscription
   • Channel statistics updates (subscriber count, total views)
   • Channel bulletin posted

5. Live Streaming (optional)

   • Live broadcast started / ended
   • Live chat messages

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement Google OAuth 2.0 flow in account-create.ts (reuse patterns from google-calendar)
• Create YouTube API utilities in utils.ts (handle pageToken pagination and quota management)
• Implement sync logic in schedule.ts for videos, playlists, comments, and channel activity
• Convert YouTube data to CORE activity format
• Add webhook support via YouTube Push Notifications (PubSubHubbub/WebSub)
• Add error handling and quota management
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• YouTube Data API v3 uses Google's standard OAuth 2.0 flow (can share auth patterns with other Google integrations)
• API uses quota system instead of simple rate limiting: each request costs quota units (default 10,000 units/day)
  • Read operations: ~1 unit per request
  • Write operations: ~50 units per request
  • Video uploads: ~1,600 units
  • Search: ~100 units per request
• Pagination uses pageToken / nextPageToken pattern
• Use part parameter to request only needed resource properties (reduces quota cost)
• Push notifications via PubSubHubbub for real-time video upload notifications
• fields parameter can further filter response to reduce payload
• ETags support for conditional requests to save quota
• All timestamps in ISO 8601 format

Resources

• YouTube Data API v3 Reference
• OAuth 2.0 for Web Server Apps
• API Quota Calculator
• YouTube API Guide 2026
• Push Notifications
• Google API Console

Labels

enhancement, good first issue, integration, new-feature, new-integration