New Integration: Twitter

Description

Add Twitter/X integration to sync tweets, mentions, likes, followers, and social engagement activity into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/github/ - Similar event-driven system
• integrations/linear/ - Project management integration
• integrations/slack/ - For messaging reference

Required Files Structure

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

X (Twitter) API v2 Integration

OAuth Setup

• Use OAuth 2.0 (Authorization Code Flow with PKCE)
• Authorization URL: https://x.com/i/oauth2/authorize
• Token URL: https://api.x.com/2/oauth2/token
• Required scopes:
  • tweet.read - Read tweets
  • tweet.write - Post and delete tweets
  • users.read - Read user profile information
  • follows.read - Read following/followers lists
  • follows.write - Follow/unfollow users
  • like.read - Read liked tweets
  • like.write - Like/unlike tweets
  • bookmark.read - Read bookmarks
  • list.read - Read lists
  • offline.access - Refresh token support (tokens expire after 2 hours without this)
  • space.read - Read Spaces
  • dm.read - Read direct messages

Base URL

• https://api.x.com/2 (X API v2)

Key Endpoints

• POST /2/tweets - Create a tweet
• DELETE /2/tweets/{id} - Delete a tweet
• GET /2/tweets/{id} - Get a tweet by ID
• GET /2/tweets - Get multiple tweets by IDs
• GET /2/tweets/search/recent - Search recent tweets (last 7 days)
• GET /2/tweets/search/all - Full-archive search (Academic/Enterprise)
• GET /2/users/{id} - Get user by ID
• GET /2/users/by/username/{username} - Get user by username
• GET /2/users/me - Get authenticated user
• GET /2/users/{id}/tweets - Get user's tweets (timeline)
• GET /2/users/{id}/mentions - Get user's mentions
• GET /2/users/{id}/followers - Get user's followers
• GET /2/users/{id}/following - Get user's following
• POST /2/users/{id}/following - Follow a user
• DELETE /2/users/{source_id}/following/{target_id} - Unfollow a user
• GET /2/users/{id}/liked_tweets - Get user's liked tweets
• POST /2/users/{id}/likes - Like a tweet
• DELETE /2/users/{id}/likes/{tweet_id} - Unlike a tweet
• GET /2/users/{id}/bookmarks - Get bookmarks
• GET /2/users/{id}/list_memberships - Get lists user is a member of
• GET /2/tweets/{id}/retweeted_by - Users who retweeted
• GET /2/tweets/{id}/liking_users - Users who liked
• GET /2/tweets/{id}/quote_tweets - Get quote tweets
• GET /2/dm_events - Get DM events

Events to Track

1. Tweet Events

   • Tweet posted
   • Tweet deleted
   • Tweet reply posted
   • Quote tweet created

2. Engagement Events

   • Tweet liked/unliked
   • Tweet retweeted
   • Tweet bookmarked
   • Tweet replied to

3. Mention Events

   • User mentioned in tweet
   • User mentioned in reply

4. Follow Events

   • New follower gained
   • User followed someone
   • User unfollowed

5. DM Events

   • Direct message received
   • Direct message sent

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.0 with PKCE flow in account-create.ts
• Create X API utilities in utils.ts with tweet expansion helpers
• Implement sync logic in schedule.ts for timeline, mentions, and engagement
• Convert X events to CORE activity format
• Handle tweet expansions (author, media, referenced tweets)
• Implement pagination with pagination tokens
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• X API v2 is the current version; v1.1 is legacy
• OAuth 2.0 with PKCE is required (not basic OAuth 2.0)
• Access tokens expire after 2 hours; use offline.access scope for refresh tokens
• Refresh tokens can be used to obtain new access tokens
• API access tiers: Free, Basic ($100/mo), Pro ($5,000/mo), Enterprise
  • Free: Tweet posting + reading + user lookup (limited)
  • Basic: 10,000 tweets/month read, 50,000 users/month
  • Pro: 1M tweets/month read, full search archive
• Use tweet.fields, user.fields, expansions query params to control response data
• Rate limits vary by endpoint and tier (e.g., 300 requests/15 min for tweet lookup on Basic)
• No native webhook support in v2 for most events; use polling
• Filtered stream available for real-time tweet matching (Pro+ tier)

Resources

• X API v2 Documentation
• X API v2 Authentication Mapping
• OAuth 2.0 Authorization Code with PKCE
• X API v2 Endpoints
• X Developer Portal
• twitter-api-v2 npm package

Labels

enhancement, integration, new-feature