feat(routes-f): scheduled streams, creator recommendations, stream analytics & push tokens

[codebestia]

Summary

Adds four self-contained practice API routes under app/api/routes-f/, each
fully scoped to its own subfolder (route handler, types, seed data, helpers and
tests). No shared app code is imported or modified — every route is independent
and mergeable in any order.

Routes

1. GET /api/routes-f/upcoming-streams

Lists streams creators have scheduled but not yet started.

• Query: within_hours (default 48, max 2 weeks), optional category
• Returns { scheduled: [...] }, future-only, filtered by time window +
  category, sorted by starts_at ascending
• Bundled seed schedule data (includes a stale past entry that is excluded)

2. GET /api/routes-f/similar-creators

Recommends creators similar to a given creator.

• Query: creator_id (required), limit (default 10, max 50)
• Returns { creators: [{ creator, similarity_score, reason }] }
• similarity_score = jaccard(categories) + jaccard(follower set) (range 0..2),
  zero-score creators dropped, follower sets never leaked in the response
• Bundled seed graph + category data

3. GET /api/routes-f/stream-analytics

Computes a single live or past stream's analytics summary.

• Query: stream_id (required)
• Returns { duration_minutes, peak_viewers, average_viewers, unique_viewers, total_messages, total_tips_usdc }
• Live streams measure duration relative to now; completed streams use their
  recorded end time
• Bundled seed session data (live + completed sessions)

4. POST / DELETE /api/routes-f/push-token

Registers or removes a viewer's push notification token (FCM / APNs).

• POST { viewer_id, platform: ios|android|web, token } -> { token_id }
• DELETE by token_id or by viewer_id + platform
• Tokens deduplicated per viewer+platform: re-registering replaces the token
  value while reusing the token_id slot; identical re-registration is idempotent

Tests

Each route ships with a Node-environment Jest suite covering validation, the
core behavior (time/category filters, Jaccard overlap shapes, live vs completed
streams, register/replace/remove lifecycle) and response shape.

Related Issues

Closes #1008
Closes #1009
Closes #1016
Closes #1019

[vercel]

@codebestia is attempting to deploy a commit to the david's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@codebestia 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