Project creatortrack social platforms expansion

URL: https://mkdocs.justinsforge.com/memory/general/project_creatortrack_social_platforms_expansion/

CreatorTrack's social data layer (feat/social-data-layer-and-scripts branch) currently only ingests YouTube. Justin wants TikTok, Instagram, and Facebook added for reach/retention data on Gus the Bass content, cross-linked to the matching YouTube upload even when posted on different days.

Current state (as of 2026-07-15): Connect flows, token refresh, and paginated fetchers for all three platforms already exist in code (built in Tasks 2/7 of the plan) but are flagged "untested against live tokens" because no account has ever completed the OAuth dance. The blocker is purely a missing secrets file: ~/.forge-secrets/creatortrack-social.env does not exist yet. Once Justin creates the developer apps, Claude provisions that file and the existing backfill pulls each platform's catalog the same way it did YouTube's.

Setup requirements per platform: - Facebook + Instagram: one Meta app under Justin's Meta Business account covers both (~20 min). Gus's IG must be Creator/Business and linked to the Gus the Bass FB Page. Because Justin is the app's own admin, no Meta app review is required connecting his own accounts, review only matters if other CreatorTrack users connect their accounts later. - TikTok: developer app at developers.tiktok.com with Login Kit, sandbox mode, Gus as test user. TikTok's basic API has no retention/watch-time data, only views/likes/comments/shares. Retention needs TikTok's Business API tier, which requires a real audit.

Cross-platform video linking design: schema already reserves social_videos.script_id so one canonical piece of content can map to N platform posts regardless of posting date. Matching pipeline: (1) auto-match ~90% via duration-within-1-second + fuzzy title/caption similarity + published-within-14-days; (2) embedding match for the rest, reusing the YouTube embeddings Task 15 is generating, embed TikTok/IG captions and cosine-match into the same space (works even when retitled per platform); (3) small human review queue in the UI for the ambiguous tail rather than silent auto-linking.

Sequencing decision: deliberately deferred as Phase 2, after the in-flight YouTube-only branch ships. The only human steps in Phase 2 are the two developer-app setups (Meta + TikTok); everything else is agent work.

Why: this generalizes the reach/retention analytics Justin already has for YouTube to Gus's other posting platforms, and the linking strategy avoids double-counting a single video reposted across platforms as separate content.

How to apply: before starting Phase 2 work, check whether ~/.forge-secrets/creatortrack-social.env now exists (Justin may have completed the app setups) and whether the FB/IG/TikTok connect code has since been tested against live tokens. Do not re-propose a different linking design, the script_id + duration/title + embedding approach is already decided.

[Claude Code]