Social Integrations

Social Integrations — Platform Connection Guide

Purpose

SYNTHEX integrates with 9 social media platforms. Each platform has its own OAuth flow, API quirks, rate limits, and webhook formats. This skill documents the shared architecture, per-platform differences, and the common patterns for adding or debugging platform support.

Platform Matrix

Supporting files:

• twitter-sync-service.ts — Twitter-specific analytics sync
• competitor-fetcher.ts — Cross-platform competitor data
• mention-fetcher.ts — Cross-platform mention tracking
• sentiment-analyzer.ts — NLP sentiment analysis for social content

Base Service Contract

File: lib/social/base-platform-service.ts Purpose: Defines the interface all platform services must implement

PlatformCredentials:

interface PlatformCredentials {
  accessToken: string;
  refreshToken?: string;
  expiresAt?: Date;
  platformUserId?: string;
  platformUsername?: string;
  scopes?: string[];
}

TokenRefreshCallback: Callback for persisting refreshed credentials to DB. Platform services call this when they automatically refresh an expired token.

SyncAnalyticsResult: Standardised analytics response with metrics (impressions, engagements, followers, following, posts, likes, comments, shares, reach, profileViews) and optional daily/per-post breakdowns.

Key design pattern: Every platform service extends the base contract. This ensures the dashboard can display analytics from any platform using the same component structure.

OAuth Connection Flow

User clicks "Connect [Platform]"
  │
  ▼
Client: oauth-handler.ts → POST /api/auth/oauth/{provider}
  │
  ▼
Server: Generate PKCE challenge (lib/auth/pkce.ts)
  │  - generateCodeVerifier() → 32 bytes crypto-random
  │  - generateCodeChallenge() → SHA-256 hash
  │  - Store state in Redis/DB/memory (fallback chain)
  │
  ▼
Redirect to platform's OAuth consent screen
  │
  ▼
User grants permissions → Platform redirects to callback URL
  │
  ▼
Server: /api/auth/oauth/{provider}/callback
  │  - Verify PKCE state
  │  - Exchange code for tokens
  │  - Encrypt tokens (AES-256-GCM)
  │  - Store in PlatformConnection table
  │
  ▼
Redirect to /dashboard/settings with success toast

PKCE storage fallback: Redis → Database (OAuthPKCEState) → In-memory

Token storage: Access and refresh tokens are encrypted at rest using lib/encryption/api-key-encryption.ts before writing to the database.

Webhook Architecture

Signature Verification

File: lib/webhooks/signature-verifier.ts Class: SignatureVerifier

Platform-specific secrets:

twitter   → TWITTER_WEBHOOK_SECRET
facebook  → META_WEBHOOK_SECRET
instagram → META_WEBHOOK_SECRET (shared with Facebook)
tiktok    → TIKTOK_WEBHOOK_SECRET
linkedin  → LINKEDIN_WEBHOOK_SECRET
pinterest → PINTEREST_WEBHOOK_SECRET
youtube   → GOOGLE_WEBHOOK_SECRET
threads   → META_WEBHOOK_SECRET (shared with Facebook/Instagram)
reddit    → REDDIT_WEBHOOK_SECRET
stripe    → STRIPE_WEBHOOK_SECRET
internal  → INTERNAL_WEBHOOK_SECRET

Security: Uses crypto.createHmac() with timingSafeEqual() to prevent timing attacks. All signatures are verified before any processing occurs.

Webhook Handler

File: lib/webhooks/webhook-handler.ts Class: WebhookHandler

Two processing modes:

1. Synchronous (serverless): receiveAndProcess() — Verifies signature, parses event, runs all registered handlers inline within the HTTP request. Required for Vercel because there is no long-lived process to poll a queue.

2. Async queue (long-lived process): receive() + start() — Enqueues events and processes them via a polling interval. Only for traditional servers.

Event types: WebhookEventType covers platform-specific events like post.created, comment.received, analytics.updated, mention.detected.

Social Webhook Handlers

File: lib/webhooks/social-webhook-handlers.ts Purpose: Platform-specific webhook event processing (analytics sync, mention tracking, engagement updates)

Per-Platform Notes

X (Twitter)

• Dual OAuth: Supports both OAuth 2.0 (user context) and OAuth 1.0a (app context)
• Direct API vars: TWITTER_API_KEY, TWITTER_API_SECRET, TWITTER_ACCESS_TOKEN, TWITTER_ACCESS_TOKEN_SECRET, TWITTER_BEARER_TOKEN
• Sync service: Dedicated twitter-sync-service.ts for analytics sync
• Rate limits: Strict per-endpoint limits, tracked per 15-minute window

Meta (Facebook, Instagram, Threads)

• Shared webhook secret: All three platforms use META_WEBHOOK_SECRET
• Graph API: Shared base URL (graph.facebook.com) with platform-specific edges
• Page tokens: Facebook requires page-level tokens (not user tokens) for posting

LinkedIn

• Direct API vars: LINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET
• Organisation posts: Requires w_organization_social scope for company page posting
• UGC API: Uses User-Generated Content API for post creation

YouTube

• Data API vars: YOUTUBE_API_KEY, YOUTUBE_CLIENT_ID, YOUTUBE_CLIENT_SECRET
• Quota system: YouTube Data API uses quota units (not simple rate limits)
• PubSubHubbub: Webhook notifications via Google's PubSubHubbub hub

Common Mistakes

Environment Variables

File Index

Reference skill: This is a read-only architecture guide — it documents existing systems and does not generate creative or code output. No capability uplift block is needed.