feat: implement X (Twitter) integration module

[Georgechisom]

Summary

Complete X (Twitter) integration module with API client, caching, graceful degradation, comprehensive mocked tests, and full documentation. All implementations follow backend module conventions with Zod validation and AppError handling.

Changes

Fetch X Follower/Engagement Metrics

• Created x.service.ts with XApiClient for X API v2 integration
• Fetches user metrics using bearer token authentication
• Normalizes follower count and calculates engagement score
• Engagement = tweet_count / followers_count (activity ratio)
• Caches results in PostgreSQL XAccount model for performance
• Handles rate limits, 404s, and API errors properly

Graceful Degradation When X is Down

• Implements fallback to cached data when API unavailable
• Configurable cache expiration with maxCacheAge parameter
• Falls back on ServiceUnavailableError (503, rate limits, network issues)
• Validates cache age before using fallback data
• Logs API failures and fallback usage for monitoring
• Returns cached data with original fetchedAt timestamp

X Integration Tests (Mocked)

• Comprehensive test suite with no real network calls
• Mocked fetch API responses using vitest fixtures
• Tests cover fresh data fetching, caching, engagement calculation
• Tests fallback behavior, rate limiting, API errors
• Tests cache expiration and stale data rejection
• Tests zero followers edge case and missing bearer token
• All tests isolated with cleanup in afterEach

X Integration Documentation

• Complete README.md with setup instructions
• Documents required X API credentials and scopes
• API endpoints documentation with request/response examples
• Service functions usage examples
• Engagement calculation explanation
• Graceful degradation flow diagram
• Error handling patterns
• Best practices and future enhancements

Module Structure

backend/src/modules/x/
├── x.types.ts       - TypeScript interfaces
├── x.schema.ts      - Zod validation schemas
├── x.service.ts     - Business logic and X API client
├── x.controller.ts  - Express request handlers
├── x.routes.ts      - Router configuration
├── x.test.ts        - Comprehensive test suite
└── README.md        - Complete documentation

API Endpoints

GET /api/v1/x/metrics/:handle

Fetches fresh metrics with optional fallback

• Query params: useFallback (default: true), maxCacheAge (default: 24h)
• Returns: handle, followers, engagement, fetchedAt

GET /api/v1/x/cached/:handle

Retrieves cached metrics without API call

• Returns cached data or 404

Key Features

• X API v2 bearer token authentication
• Automatic caching in PostgreSQL
• Graceful degradation with configurable fallback
• Rate limit handling (429 errors)
• Engagement score calculation
• Comprehensive error handling with AppError
• No real network calls in tests
• Full Zod input validation

Additional Changes

• Added ServiceUnavailableError (503) to AppError classes
• Added TipStatus enum to Prisma schema
• Updated User model relations (tips, leaderboard, notifications)
• Mounted X router in app.ts at /api/v1/x
• Updated enums.ts exports for Prisma types

Environment Variables

X_API_BEARER_TOKEN=your_bearer_token_here
X_API_BASE_URL=https://api.twitter.com/2

Cache Strategy

1. Try fresh API fetch
2. Cache successful responses
3. On API failure, check cached data
4. Validate cache age against maxCacheAge
5. Return cached data or propagate error

Closes #979
Closes #971
Closes #978
Closes #977

[drips-wave]

@Georgechisom Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Akanimoh12]

Please resolve conflicts

[Georgechisom]

fixed