Twitter/X social adapter package

[arberx]

Summary

Implement the Twitter/X social platform adapter using X API v2.

API Details

• Tier required: Basic ($100/month) — Free tier is write-only
• Search endpoint: GET /2/tweets/search/recent with query operators like url:"example.com" and "brand name"
• Lookback: 7 days only (recent search, no full-archive on Basic)
• Rate limits: 60 requests/15 min for search, 10,000 tweets/month cap
• Auth: OAuth 2.0 Bearer token (app-only) for search

Data extracted

Tweet text, author username/name/followers, engagement (likes, retweets, replies, quotes, impressions, bookmarks), URLs shared, hashtags, creation timestamp.

Package structure

packages/social-twitter/
  src/adapter.ts      -- implements SocialPlatformAdapter
  src/normalize.ts     -- X API v2 response → SocialMentionResult[]
  src/types.ts         -- X API v2 response types
  src/index.ts
  test/index.test.ts
  package.json         -- @ainyc/canonry-social-twitter

UX Considerations

• Clearly communicate 7-day search limitation in CLI output and UI
• Document the $100/mo cost requirement prominently
• Implement aggressive caching/dedup to minimize API calls against monthly cap

Depends on

• Social contracts issue (Social contracts: SocialPlatformAdapter interface and types #95)
• Job runner integration issue (Social monitoring job runner integration #100)

Acceptance Criteria

• Adapter validates config (requires Bearer token)
• Healthcheck verifies X API connectivity
• searchMentions() returns normalized results
• Respects rate limits (60/15min)
• Unit tests with mocked X API responses
• 7-day limitation clearly surfaced in output