Add Watchlist Feature with Episode Tracking to NyumaFlix

[Teamial]

Add Watchlist Feature with Episode Tracking

Overview

Adds a watchlist feature that lets users track viewing progress for movies and TV shows, with episode tracking for TV shows and status management.

Features

Core functionality

• Add/remove movies and TV shows to/from watchlist
• Track last watched episode and season for TV shows
• Status management: Watching, Waiting for New Episodes, Finished
• Protected watchlist route (redirects to login if not authenticated)
• Episode progress indicator showing last watched episode with badge

Status management

• Watching: Default status when adding items
• Waiting for New Episodes: Auto-detected when all available episodes are watched and show is not ended (can be manually set)
• Finished: Manual only (user must explicitly mark)

UI/UX

• Watchlist button in hero section and sidebars for movies/TV shows
• Watchlist page with three sections (Watching, Waiting, Finished)
• Grid/list view toggle (matches existing MediaContentGrid pattern)
• Status toggle buttons on watchlist items
• Last watched episode badge indicator (different style from selected episode)
• Watchlist link in navbar (visible when authenticated)

Technical implementation

Database

• New watchlist table with:
  • User association (cascade delete)
  • Content ID and media type tracking
  • Status field (watching/waiting/finished)
  • Episode/season tracking for TV shows
  • Timestamps for tracking and updates
  • Unique constraint on (userId, contentId, mediaType)

API routes

• GET /api/watchlist - Fetch user's watchlist
• POST /api/watchlist - Add item to watchlist
• PATCH /api/watchlist/[id] - Update watchlist item status/progress
• DELETE /api/watchlist/[id] - Remove item from watchlist
• POST /api/watchlist/progress - Track watch progress when episode is selected

Server actions

• getUserWatchlist() - Fetch user's watchlist items
• getWatchlistItem() - Get specific watchlist item
• checkAndUpdateWaitingStatus() - Auto-detect "Waiting for New Episodes" status
• batchCheckWaitingStatus() - Batch check for periodic updates

Components

• WatchlistButton - Add/remove from watchlist button
• EpisodeProgressIndicator - Last watched episode badge
• WatchlistSection - Section component for status groups
• WatchlistClient - Client component for watchlist page

Integration points

• Episode store: Tracks progress when episode is selected
• Season episodes: Shows last watched episode indicator
• Hero section: Watchlist button added
• Movie/TV show pages: Watchlist buttons in sidebars
• Navigation: Watchlist link added (authenticated users only)

Database migration

• Migration file: 0002_add_watchlist_table.sql
• Run migration: npm run db:push or npm run db:migrate

Notes

• Movies: Included in watchlist but no episode tracking (single content)
• TV shows: Full episode/season tracking with progress indicators
• Auto-detection: "Waiting for New Episodes" can be triggered periodically via batchCheckWaitingStatus()
• UI consistency: Matches existing glassmorphism design patterns
• Authentication: All watchlist features require user authentication

Testing checklist

• [ ] Add movie to watchlist
• [ ] Add TV show to watchlist
• [ ] Track episode progress by selecting episodes
• [ ] View watchlist page with all three sections
• [ ] Change status using toggle buttons
• [ ] Remove items from watchlist
• [ ] Verify protected route redirects to login when not authenticated
• [ ] Check last watched episode indicator appears correctly
• [ ] Verify watchlist link appears in navbar when authenticated

Screenshots

---

Migration required: Run npm run db:push to create the watchlist table before testing.

[vercel[bot]]

@Teamial is attempting to deploy a commit to the nyumat's projects Team on Vercel.

A member of the Team first needs to authorize it.

[vercel[bot]]

Deployment failed with the following error:

The provided GitHub repository does not contain the requested branch or commit reference. Please ensure the repository is not empty.

[vercel[bot]]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
nyumatflix	Ready	Preview	Comment	Nov 19, 2025 9:08am

[Nyumat]

@Teamial what's your thoughts on moving the watchlist link btn into the user avatar navigation dropdown?

my thinking: more visible items in the header could be less than ideal on smaller devices. the current breakpoint(s) remove "Home" once it gets to md (tailwind); what if it shoved the watchlist there since it's already binded to being logged-in?

[Teamial]

I completely agree with that logic. Moving it to the dropdown solves the responsiveness issue on md screens and groups it better with the other user-specific actions.

Want me to push that update to this branch real quick?

[Nyumat]