Fan Subscription Feed API — Cursor, Visibility, Scale Path (Hard)

[aji70]

Task: Fan Subscription Feed API — Cursor, Visibility, Scale Path (Hard)

Overview

No aggregated timeline exists. Implement the core fan feed API with cursor pagination, strict visibility, stable ordering, empty-state semantics, and query plans that won’t melt under many subscriptions — not IN (all creator ids) without thought.

---

Scope (must all ship)

API

• GET /api/v1/feed/subscriptions?cursor&limit&filter? — authenticated fan
• Envelope: { data, nextCursor, hasMore } (match existing pagination conventions)
• filter: all | media | text (or documented equivalent)
• Default limit + hard max (e.g. 50)

Semantics

• Only active subscriptions
• Include posts visible to fan: public + subscribers from those creators; never others’ private
• Exclude soft-deleted posts and non-published
• Order publishedAt DESC, id DESC for stable cursors
• Cursor opaque (base64 of {publishedAt,id}) — no raw offset pages as primary

Query design

• Prefer SQL that scales: join subscriptions ↔ posts with proper indexes
• Document EXPLAIN for representative seed (in PR or docs)
• Soft upper bound: if fan has >N subscriptions, still correct (test with ≥25 creators seeded)

Caching (optional but scored)

• Document why HTTP cache not used (auth) OR ETag stub

Errors

• Unauthenticated → 401
• Invalid cursor → 400 with VALIDATION_ERROR

Swagger + docs

• docs/feed.md: cursor format, visibility, empty vs unsubscribed

Testing (≥12)

• Auth required
• Sees subscriber-only from subscribed creator
• Does not see subscriber-only after cancel
• Does not see other creators’ posts
• Cursor page 2 continuity + no dupes
• Empty subscriptions → empty data hasMore: false
• Filter media/text
• Soft-deleted excluded
• Invalid cursor 400
• Ordering stability with same timestamp

---

Deliverables

• FeedModule (or posts extension), DTOs, indexes/migration, Swagger
• Docs + ≥12 tests

---

Acceptance Criteria

• Cursor feed correct under visibility + cancel immediacy
• No duplicate/gap under stable sort
• Indexes/docs address multi-subscription scale
• CI green

Out of scope

• Ranked/ML feed
• Following non-paid “follow” graph (subscriptions only)

[sundayjob996]

hi maintainer am a full-stack dev can i please jump on this issue

[grantfox-oss]

🦊 GrantFox — @sundayjob996 has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #58)
2. Your PR will be reviewed by the MyFanss maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@sundayjob996's PR #74 was approved and merged by @aji70.

🏆 @sundayjob996: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (153 total points). Track your full progress on GrantFox.

👏 Great work, @sundayjob996! Keep contributing to MyFanss.