Engineering
The wait-to-binge math, and the two decisions that keep it honest
The wait-to-binge saving, the show card’s “subscribe on the finale” line, the Watch Plan’s window label and the finale-eve push all come from one small module. This note is what that module computes, and the two decisions that keep it honest.
Classifying a season
The schedule for a season is a list of episode air dates. Count the distinct dates. One is a full drop. Two or three are batched volumes. Four or more is weekly. Checked against live data: a full-drop season has one date, a two-volume season has two, a ten-episode weekly season has nine or ten. That classification runs on the sync job and is stored on the tracked show, with the episode count and the finale date.
The saving
Billing is assumed to be a 30-day cycle. From today to the finale, count the cycles a subscription started now would cross; subscribing on the finale instead costs one cycle to binge. The saving is the difference, times the monthly price. When the finale is inside the next cycle the difference is zero and nothing is shown. There is no point telling someone they can save nothing.
Decision one: unknown beats wrong
A season with undated episodes, or fewer episodes listed than the season is known to have, is classified as unknown, and unknown suppresses every wait-to-binge surface. The reason is what an incomplete schedule looks like: a premiere with one date and nothing after it is indistinguishable from a full drop. Treating it as one would tell the user to subscribe now for a season that is going to drip out for ten weeks, which is the exact mistake the feature exists to prevent. So the only honest answer for an incomplete schedule is “don’t know yet”, and the card says nothing until the schedule fills in.
Decision two: don’t advise waiting on a service you already hold
If any of the user’s subscriptions already gives them the service, through a direct bill, a bundle or a carrier perk, the saving is fiction: they would be paying those cycles anyway. The API withholds the wait-to-binge line whenever another row already covers the service. The Watch Plan applies the same test when it labels a future window, and the finale-eve push is only sent for a service the user doesn’t hold.
One module, four surfaces
The cycle length, the classification thresholds and every copy string live in one shared file that both the API and the app import. The show card, the plan label, the push and the wake-up message for a weekly new season all read it. A change to the cycle length, or to a sentence, lands everywhere in one commit, and the tests for the maths are the tests for all four.