docs(social): the scrape contract — per-platform posts, what one scrape stores, post engagement, follower history (app#2018)

Merged
SW
2mo ago
+126-8

Contract PR for recoupable/app#2018 (scrape persistence keystone). Absorbs the docs rows of app#2017 (posts per platform) and app#2026 (history on /socials).

What changes

POST /api/socials/{id}/scrape (social.json)

  • Credits formula (5 + posts), a per-platform table for posts (honored / actor parameter / default when omitted), a "What gets stored" list (profile, daily follower snapshot, posts with engagement, Instagram comments + commenter enrichment) and the one-hop rule for fan discovery.
  • Corrects the old text: startInstagramProfileScraping never forwards posts, so Instagram ignores it and always returns the profile's latest posts (up to 12); TikTok honors it (resultsPerPage). The previous "other platforms ignore this parameter" was wrong for TikTok and silent about Instagram.
  • posts parameter description shortened to point at the table.

GET /api/artists/{id}/posts (social.json)

  • ArtistPost gains nullable views, likes, comments, reposts, each with the per-platform source field (e.g. TikTok playCount, X viewCount); description states they are the values at the last scrape and null where the platform does not report them.

GET /api/artists/{id}/socials (releases.json)

  • New history=<days> query (1–90) returning history: SocialSnapshot[] per profile, newest first, one point per social per day (latest scrape that day wins). New SocialSnapshot schema (captured_at, follower_count, following_count, post_count).
  • Documents page / limit (the validator already accepts them) and the real 401 / 403 / 404 the route returns; previously only 400 was listed.

POST /api/artist/socials/scrape (releases.json) — posts description aligned with the single-social page, credits per profile stated.

GET /api/artists/{id}/fans (releases.json) — states that fans are commenters on scraped posts (Instagram today) and that the commenter profile run fills avatar/bio/follower counts. (The per-platform coverage table stays with app#2024.)

Merge order

docs (this) → database (social_snapshots, posts engagement columns, apify_scraper_runs lineage) → api keystone → api budget. This PR is the contract the api PR is tested against.

Edits were applied as anchored text replacements (the files do not round-trip byte-identically through json.dumps); both files re-parse.

🤖 Generated with Claude Code

https://claude.ai/code/session_012PS8hmiwR1rGD6c41n6gD8

Summary by cubic

Defines the scrape persistence contract in the OpenAPI specs for recoupable/app#2018: per-platform post depth, what one scrape stores, post engagement fields, and follower history.

What changed

  • POST /api/socials/{id}/scrape now documents the credits formula (5 + posts) and a per-platform table; Instagram ignores posts and always returns the latest 12 posts, while TikTok honors it — correcting previously wrong text.
  • ArtistPost gains nullable views, likes, comments, and reposts, each with the per-platform source field.
  • GET /api/artists/{id}/socials adds history=<days> (1–90) returning SocialSnapshot[] per profile and documents the real 401/403/404 responses; following_count and post_count are null where the platform does not report them.
  • GET /api/artists/{id}/fans now states fans are commenters on scraped posts (Instagram today) and that the enrichment pass fills avatar, bio, and follower and following counts.
  • The batch scrape posts description is aligned with the single-social endpoint.