@tribe-nest/forge 3.34.0 → 3.35.0

package/src/ui/headless/film/_tests/filmRules.spec.ts

@@ -0,0 +1,531 @@
+import { describe, it, expect } from "vitest";
+import { buildFilmPlaybackGate, msUntil } from "../useFilmPlayback";
+import {
+  absolutizeFilmUrl,
+  withFilmSessionToken,
+  filmErrorCode,
+  filmErrorStatus,
+  filmErrorMessage,
+} from "../../../../data/queries/useFilmPlaybackSession";
+import {
+  canWatchFilmEpisode,
+  cheapestFilmRentalOption,
+  filmFromPriceCents,
+  filmRentalCoversEpisode,
+  filmRentalOptions,
+  groupFilmEpisodesBySeason,
+  isFilmEpisodeReleased,
+  nextFilmEpisode,
+  splitDurationSec,
+  splitRemainingMs,
+  splitRentalHours,
+  type PublicFilmBase,
+  type PublicFilmEpisode,
+  type PublicFilmRental,
+  type PublicFilmRentalOption,
+} from "../../../../data/queries/useFilms";
+import { buildFilmSchema } from "../../../../utils/structuredData";
+
+/**
+ * The pure half of film rentals, as both the styled blocks and any custom player
+ * read it.
+ *
+ * None of this is the entitlement - every playback endpoint re-derives coverage,
+ * liveness and the session holder from the database on every request, so being
+ * wrong here draws a button that 404s rather than granting anything. What being
+ * wrong here DOES cost is a person stranded on the wrong sentence: a gate that
+ * says "sign in" to somebody already signed in, or "cannot be played" to
+ * somebody who only needed to.
+ */
+
+const episode = (over: Partial<PublicFilmEpisode> = {}): PublicFilmEpisode => ({
+  id: "ep-1",
+  filmId: "film-1",
+  seasonNumber: 1,
+  episodeNumber: 1,
+  title: null,
+  description: null,
+  durationSec: 2700,
+  availableAt: null,
+  isFreePreview: false,
+  ...over,
+});
+
+const option = (over: Partial<PublicFilmRentalOption> = {}): PublicFilmRentalOption => ({
+  id: "opt-48",
+  label: null,
+  priceCents: 200_00,
+  durationHours: 48,
+  position: 0,
+  ...over,
+});
+
+const film = (over: Partial<PublicFilmBase> = {}): PublicFilmBase => ({
+  id: "film-1",
+  kind: "series",
+  title: "The Four",
+  slug: "the-four",
+  description: null,
+  currency: "NGN",
+  rentalOptions: [option()],
+  fromPriceCents: 200_00,
+  publishedAt: "2026-01-01T00:00:00.000Z",
+  cover: null,
+  ...over,
+});
+
+const rejection = (status: number, body?: Record<string, unknown>) => ({ response: { status, data: body } });
+
+describe("the playback gate", () => {
+  it("sends a signed-OUT 401 to sign in", () => {
+    const gate = buildFilmPlaybackGate({ error: rejection(401), isAuthenticated: false });
+    expect(gate?.kind).toBe("sign_in_required");
+  });
+
+  it("does NOT tell a signed-IN 401 to sign in", () => {
+    // Signing in is what they already did. The refusal is about the SESSION
+    // token, not about who they are, so pointing them at the login form is a
+    // loop with no exit.
+    const gate = buildFilmPlaybackGate({ error: rejection(401), isAuthenticated: true });
+    expect(gate?.kind).toBe("unavailable");
+  });
+
+  it("sends a 403 out of the session it is in, not back into one", () => {
+    const gate = buildFilmPlaybackGate({ error: rejection(403), isAuthenticated: true });
+    expect(gate?.kind).toBe("wrong_account");
+  });
+
+  it("reads a 404 as no rental when nothing is known about one", () => {
+    expect(buildFilmPlaybackGate({ error: rejection(404), isAuthenticated: true })?.kind).toBe("no_rental");
+  });
+
+  it("reads the SAME 404 as expired once a rental is known", () => {
+    // The status cannot tell these apart on purpose - a 403 for somebody else's
+    // rental would confirm the id exists. The caller's own knowledge is what
+    // turns "you never had this" into "yours ran out", and those two need
+    // different buttons.
+    const gate = buildFilmPlaybackGate({ error: rejection(404), isAuthenticated: true, hadRental: true });
+    expect(gate?.kind).toBe("expired");
+  });
+
+  it("keeps the API's own sentence when it sent one", () => {
+    const gate = buildFilmPlaybackGate({
+      error: rejection(404, { message: "That episode is not out yet." }),
+      isAuthenticated: true,
+    });
+    expect(gate?.message).toBe("That episode is not out yet.");
+  });
+
+  it("is null when nothing failed", () => {
+    expect(buildFilmPlaybackGate({ error: null, isAuthenticated: true })).toBeNull();
+  });
+
+  it("survives a rejection that is not axios-shaped", () => {
+    for (const thrown of [new Error("offline"), "nope", 42, {}, undefined]) {
+      const gate = buildFilmPlaybackGate({ error: thrown, isAuthenticated: true });
+      if (thrown === undefined) expect(gate).toBeNull();
+      else expect(gate?.kind).toBe("unavailable");
+    }
+  });
+});
+
+describe("reading a rejection", () => {
+  it("pulls status, code and message without importing axios", () => {
+    const error = rejection(409, { code: "FILM_SESSION_TAKEN_OVER", message: "Playing elsewhere." });
+    expect(filmErrorStatus(error)).toBe(409);
+    expect(filmErrorCode(error)).toBe("FILM_SESSION_TAKEN_OVER");
+    expect(filmErrorMessage(error)).toBe("Playing elsewhere.");
+  });
+
+  it("returns null rather than throwing on anything else", () => {
+    for (const thrown of [null, undefined, "boom", { response: {} }, { response: { status: "409" } }]) {
+      expect(filmErrorStatus(thrown)).toBeNull();
+      expect(filmErrorCode(thrown)).toBeNull();
+      expect(filmErrorMessage(thrown)).toBeNull();
+    }
+  });
+
+  it("treats a blank message as no message", () => {
+    expect(filmErrorMessage(rejection(404, { message: "   " }))).toBeNull();
+  });
+});
+
+describe("the countdown", () => {
+  const now = new Date("2026-08-23T12:00:00.000Z");
+
+  it("is null with no window, which is what a free preview has", () => {
+    expect(msUntil(null, now)).toBeNull();
+    expect(msUntil(undefined, now)).toBeNull();
+  });
+
+  it("never runs backwards", () => {
+    // Zero IS the answer once it has run out. A negative number renders as a
+    // countdown counting up, which is how a fan learns not to trust the clock.
+    expect(msUntil("2026-08-23T11:00:00.000Z", now)).toBe(0);
+  });
+
+  it("is null for a timestamp it cannot read", () => {
+    expect(msUntil("not a date", now)).toBeNull();
+  });
+
+  it("counts the remaining milliseconds", () => {
+    expect(msUntil("2026-08-23T12:30:00.000Z", now)).toBe(30 * 60 * 1000);
+  });
+
+  it("rounds a remainder DOWN at every level", () => {
+    // 59 minutes that reads as "1 hour" is a promise the clock will not keep,
+    // and the fan finds out at the worst possible moment.
+    const split = splitRemainingMs(59 * 60_000 + 59_000);
+    expect(split).toEqual({ days: 0, hours: 0, minutes: 59, totalMinutes: 59 });
+  });
+
+  it("splits days, hours and minutes", () => {
+    const split = splitRemainingMs((26 * 60 + 5) * 60_000);
+    expect(split).toEqual({ days: 1, hours: 2, minutes: 5, totalMinutes: 1565 });
+  });
+
+  it("is null for nothing and for nonsense", () => {
+    expect(splitRemainingMs(null)).toBeNull();
+    expect(splitRemainingMs(-1)).toBeNull();
+    expect(splitRemainingMs(Number.NaN)).toBeNull();
+  });
+});
+
+describe("what a rental covers", () => {
+  it("grants EVERY episode of the title it was bought for", () => {
+    // The whole product decision in one assertion: a rental is for a title, so
+    // episode 9 of a ten-part series is covered by the same row as episode 1.
+    const rental = { filmId: "film-1" };
+    expect(filmRentalCoversEpisode(rental, episode({ id: "ep-1", episodeNumber: 1 }))).toBe(true);
+    expect(filmRentalCoversEpisode(rental, episode({ id: "ep-9", episodeNumber: 9 }))).toBe(true);
+  });
+
+  it("does NOT reach across titles", () => {
+    const rental = { filmId: "film-1" };
+    expect(filmRentalCoversEpisode(rental, episode({ id: "ep-9", filmId: "film-2" }))).toBe(false);
+  });
+
+  it("short-circuits a free preview, with or without a rental", () => {
+    const preview = episode({ id: "ep-1", isFreePreview: true });
+    expect(filmRentalCoversEpisode(null, preview)).toBe(true);
+    expect(filmRentalCoversEpisode(undefined, preview)).toBe(true);
+  });
+
+  it("covers nothing without a rental when the episode is not a preview", () => {
+    expect(filmRentalCoversEpisode(null, episode())).toBe(false);
+  });
+});
+
+/**
+ * The one question every episode row asks. One grain means one rental to ask it
+ * of, so there is no set to search and no helper that takes one.
+ */
+describe("whether an episode can be played right now", () => {
+  const rental = (over: Partial<PublicFilmRental> = {}): PublicFilmRental => ({
+    id: "r-1",
+    filmId: "film-1",
+    status: "active",
+    amountCents: 200,
+    currency: "USD",
+    rentalDurationHours: 48,
+    rentalOptionId: "opt-48",
+    paidAt: "2026-08-20T00:00:00.000Z",
+    startBy: "2026-09-19T00:00:00.000Z",
+    firstPlayedAt: null,
+    expiresAt: null,
+    refundedAt: null,
+    revokedAt: null,
+    isLive: true,
+    msRemaining: null,
+    windowMs: 48 * 3600_000,
+    ...over,
+  });
+
+  const now = new Date("2026-08-23T12:00:00.000Z");
+
+  it("opens every episode of the rented title", () => {
+    const live = rental();
+    expect(canWatchFilmEpisode(live, episode({ id: "ep-1", episodeNumber: 1 }), now)).toBe(true);
+    expect(canWatchFilmEpisode(live, episode({ id: "ep-9", episodeNumber: 9 }), now)).toBe(true);
+  });
+
+  it("does not open another title's episode", () => {
+    expect(canWatchFilmEpisode(rental(), episode({ id: "ep-9", filmId: "film-2" }), now)).toBe(false);
+  });
+
+  it("refuses a covering rental whose window has run out", () => {
+    // Covered but expired is not a reason to draw Watch: the playback endpoints
+    // re-derive liveness and would 404.
+    expect(canWatchFilmEpisode(rental({ isLive: false }), episode(), now)).toBe(false);
+  });
+
+  it("plays a free preview with no rental at all", () => {
+    const preview = episode({ id: "ep-1", isFreePreview: true });
+    expect(canWatchFilmEpisode(null, preview, now)).toBe(true);
+    expect(canWatchFilmEpisode(undefined, preview, now)).toBe(true);
+  });
+
+  it("refuses everything else with no rental", () => {
+    expect(canWatchFilmEpisode(null, episode(), now)).toBe(false);
+  });
+
+  it("holds back an unreleased episode, free preview or not", () => {
+    // Drip release is not entitlement, so it is checked separately and it wins:
+    // a free preview that is not out yet still has nothing to play.
+    const unreleased = { availableAt: "2026-08-24T00:00:00.000Z" };
+    expect(canWatchFilmEpisode(rental(), episode(unreleased), now)).toBe(false);
+    expect(canWatchFilmEpisode(null, episode({ ...unreleased, isFreePreview: true }), now)).toBe(false);
+  });
+});
+
+describe("whether an episode has been released", () => {
+  const now = new Date("2026-08-23T12:00:00.000Z");
+
+  it("treats a null release date as out", () => {
+    expect(isFilmEpisodeReleased(episode({ availableAt: null }), now)).toBe(true);
+  });
+
+  it("is inclusive at the boundary, matching the server", () => {
+    expect(isFilmEpisodeReleased(episode({ availableAt: "2026-08-23T12:00:00.000Z" }), now)).toBe(true);
+  });
+
+  it("holds back a future release", () => {
+    expect(isFilmEpisodeReleased(episode({ availableAt: "2026-08-23T12:00:00.001Z" }), now)).toBe(false);
+  });
+
+  it("treats an unreadable timestamp as released, matching the NULL arm", () => {
+    expect(isFilmEpisodeReleased(episode({ availableAt: "garbage" }), now)).toBe(true);
+  });
+});
+
+describe("what is on sale", () => {
+  const cheap = option({ id: "opt-8", priceCents: 100_00, durationHours: 8, position: 3 });
+  const dear = option({ id: "opt-48", priceCents: 200_00, durationHours: 48, position: 1 });
+
+  it("keeps the creator's own order, whatever order the payload arrived in", () => {
+    // `dear` sits at position 1 because the creator put it there with the up
+    // arrow, and the admin screen told them "Fans see these in this order, top
+    // first." Re-sorting by price here made that sentence false and made every
+    // reorder invisible, since two windows on one title rarely cost the same.
+    expect(filmRentalOptions(film({ rentalOptions: [cheap, dear] })).map((o) => o.id)).toEqual(["opt-48", "opt-8"]);
+  });
+
+  it("breaks a position tie on price, then on id", () => {
+    const a = option({ id: "b", priceCents: 200_00, durationHours: 8, position: 1 });
+    const b = option({ id: "a", priceCents: 100_00, durationHours: 12, position: 1 });
+    const c = option({ id: "a2", priceCents: 100_00, durationHours: 24, position: 1 });
+    expect(filmRentalOptions(film({ rentalOptions: [a, b, c] })).map((o) => o.id)).toEqual(["a", "a2", "b"]);
+  });
+
+  it("defaults to the CHEAPEST window even when the creator shows a dearer one first", () => {
+    // Pre-selecting the dearer window would make the default choice the one that
+    // costs more, which is a decision the fan did not make. `dear` is first in
+    // the list above, so this can never be "take index 0".
+    expect(cheapestFilmRentalOption(film({ rentalOptions: [cheap, dear] }))?.id).toBe("opt-8");
+    expect(filmFromPriceCents(film({ rentalOptions: [cheap, dear], fromPriceCents: null }))).toBe(100_00);
+  });
+
+  it("has nothing on sale when there are no live options", () => {
+    // Every window archived looks exactly like never having priced the title,
+    // and both mean the Rent button stays off the page.
+    expect(filmRentalOptions(film({ rentalOptions: [] }))).toEqual([]);
+    expect(cheapestFilmRentalOption(film({ rentalOptions: [] }))).toBeNull();
+    expect(filmFromPriceCents(film({ rentalOptions: [], fromPriceCents: null }))).toBeNull();
+  });
+
+  it("prints the server's `from` price, falling back to the cheapest option", () => {
+    expect(filmFromPriceCents(film({ rentalOptions: [dear, cheap], fromPriceCents: 100_00 }))).toBe(10000);
+    // A hand-built payload (a custom surface, a fixture) has no `fromPriceCents`
+    // and must still answer the same number rather than "not on sale".
+    expect(filmFromPriceCents({ rentalOptions: [dear, cheap] })).toBe(10000);
+  });
+
+  it("treats a zero price as a real (free) window, not as an absence", () => {
+    // An explicit 0 is a free rental somebody chose to publish, and hiding it
+    // would delete a feature. Every check is `!= null`, never truthiness.
+    const free = film({ rentalOptions: [option({ priceCents: 0 })], fromPriceCents: 0 });
+    expect(cheapestFilmRentalOption(free)?.priceCents).toBe(0);
+    expect(filmFromPriceCents(free)).toBe(0);
+  });
+
+  it("is empty or null for no film at all", () => {
+    expect(filmRentalOptions(undefined)).toEqual([]);
+    expect(filmRentalOptions(null)).toEqual([]);
+    expect(cheapestFilmRentalOption(undefined)).toBeNull();
+    expect(filmFromPriceCents(null)).toBeNull();
+  });
+
+  it("does not mutate the payload it was handed", () => {
+    // The array belongs to a react-query cache entry. Sorting it in place would
+    // reorder the very object the next render reads, which is the kind of bug
+    // that only shows up as a list that shuffles.
+    // Handed in the order the sort will CHANGE, or an in-place sort would go
+    // unnoticed here.
+    const options = [cheap, dear];
+    expect(filmRentalOptions({ rentalOptions: options }).map((o) => o.id)).toEqual(["opt-48", "opt-8"]);
+    expect(options.map((o) => o.id)).toEqual(["opt-8", "opt-48"]);
+  });
+});
+
+describe("ordering episodes", () => {
+  const list = [
+    episode({ id: "s2e1", seasonNumber: 2, episodeNumber: 1 }),
+    episode({ id: "s1e2", seasonNumber: 1, episodeNumber: 2 }),
+    episode({ id: "s1e1", seasonNumber: 1, episodeNumber: 1 }),
+  ];
+
+  it("groups by season, ascending, with episodes in order", () => {
+    expect(groupFilmEpisodesBySeason(list).map((s) => [s.seasonNumber, s.episodes.map((e) => e.id)])).toEqual([
+      [1, ["s1e1", "s1e2"]],
+      [2, ["s2e1"]],
+    ]);
+  });
+
+  it("crosses a season boundary to find the next episode", () => {
+    expect(nextFilmEpisode(list, "s1e2")?.id).toBe("s2e1");
+  });
+
+  it("ends at the last episode rather than wrapping", () => {
+    // A series still releasing weekly must end at the last one OUT, or the
+    // prompt offers a link to an episode nobody can play.
+    expect(nextFilmEpisode(list, "s2e1")).toBeNull();
+  });
+
+  it("is null for an episode that is not in the list", () => {
+    expect(nextFilmEpisode(list, "not-here")).toBeNull();
+  });
+});
+
+describe("formatting durations", () => {
+  it("splits a runtime into hours and whole minutes", () => {
+    expect(splitDurationSec(6120)).toEqual({ hours: 1, minutes: 42 });
+    expect(splitDurationSec(2700)).toEqual({ hours: 0, minutes: 45 });
+  });
+
+  it("is null for nothing and for nonsense", () => {
+    expect(splitDurationSec(null)).toBeNull();
+    expect(splitDurationSec(0)).toBeNull();
+    expect(splitDurationSec(Number.NaN)).toBeNull();
+  });
+
+  it("splits a rental window into days and hours", () => {
+    expect(splitRentalHours(48)).toEqual({ days: 2, hours: 0 });
+    expect(splitRentalHours(30)).toEqual({ days: 1, hours: 6 });
+    expect(splitRentalHours(0)).toEqual({ days: 0, hours: 0 });
+  });
+});
+
+describe("playback URLs", () => {
+  it("resolves a root-relative path against the API, not the site", () => {
+    // A root-relative path on a creator site resolves against the CREATOR's
+    // origin, where it hits the site's own router and 404s. That reads as "the
+    // player is broken".
+    expect(absolutizeFilmUrl("/public/films/a/episodes/b/manifest/master", "https://api.tribenest.co")).toBe(
+      "https://api.tribenest.co/public/films/a/episodes/b/manifest/master",
+    );
+  });
+
+  it("leaves an absolute URL alone", () => {
+    expect(absolutizeFilmUrl("https://api.example.com/x", "https://api.tribenest.co")).toBe(
+      "https://api.example.com/x",
+    );
+  });
+
+  it("does not double the slash when the API URL has a trailing one", () => {
+    expect(absolutizeFilmUrl("/x", "https://api.tribenest.co/")).toBe("https://api.tribenest.co/x");
+  });
+
+  it("attaches the token as `st`, respecting an existing query string", () => {
+    expect(withFilmSessionToken("https://a/b", "tok")).toBe("https://a/b?st=tok");
+    expect(withFilmSessionToken("https://a/b?x=1", "tok")).toBe("https://a/b?x=1&st=tok");
+  });
+
+  it("encodes a token that would otherwise break the query string", () => {
+    expect(withFilmSessionToken("https://a/b", "a+b/c=")).toBe("https://a/b?st=a%2Bb%2Fc%3D");
+  });
+
+  it("builds a subtitle src the same way it builds the manifest src", () => {
+    // A `<track>` is fetched by the BROWSER, not by the engine, so it cannot be
+    // handed a header either: the session token has to be in the URL, exactly as
+    // it is for the manifest and the key. The API deliberately sends the track
+    // URL token-free, because the heartbeat rotates the token and a baked-in one
+    // would be stale inside ten minutes.
+    const track = { url: "/public/films/a/episodes/b/subtitles/c" };
+    expect(withFilmSessionToken(absolutizeFilmUrl(track.url, "https://api.tribenest.co"), "tok")).toBe(
+      "https://api.tribenest.co/public/films/a/episodes/b/subtitles/c?st=tok",
+    );
+  });
+
+  it("does not append a SECOND token to a url that already carries one", () => {
+    // `?st=a&st=b` is parsed by Express as an array, and the schema rejects an
+    // array, so a double-appended token is a 400 on every subtitle fetch rather
+    // than a token that merely loses. Appending exactly once is the caller's
+    // job, and this pins what happens when they get it wrong.
+    const once = withFilmSessionToken("https://api/x", "a");
+    expect(withFilmSessionToken(once, "b")).toBe("https://api/x?st=a&st=b");
+  });
+});
+
+/**
+ * `buildFilmSchema` takes ONE price, because a schema.org `Offer` quotes one.
+ * The starter route feeds it `fromPriceCents` - the cheapest window - which is
+ * what the catalogue card says and what a search result should say. Quoting the
+ * dearest window would advertise a price nobody has to pay.
+ */
+const schemaSource = (over: Partial<PublicFilmBase> = {}, episodes: { durationSec?: number | null }[] = []) => {
+  const source = film(over);
+  return { ...source, rentalPriceCents: source.fromPriceCents, episodes };
+};
+
+describe("the JSON-LD a crawler reads", () => {
+  it("is a Movie for a film and a TVSeries for a series", () => {
+    expect(buildFilmSchema(schemaSource({ kind: "film" }))?.["@type"]).toBe("Movie");
+    expect(buildFilmSchema(schemaSource())?.["@type"]).toBe("TVSeries");
+  });
+
+  it("quotes the CHEAPEST window's price, in major units, as a rental", () => {
+    const schema = buildFilmSchema(
+      schemaSource({
+        rentalOptions: [option({ id: "opt-8", priceCents: 100_00, durationHours: 8 }), option()],
+        fromPriceCents: 100_00,
+      }),
+      { currency: "NGN" },
+    );
+    expect(schema?.offers).toEqual({
+      "@type": "Offer",
+      priceCurrency: "NGN",
+      price: 100,
+      availability: "https://schema.org/InStock",
+      category: "Rental",
+    });
+  });
+
+  it("emits no offer when nothing is on sale", () => {
+    const schema = buildFilmSchema(schemaSource({ rentalOptions: [], fromPriceCents: null }), { currency: "NGN" });
+    expect(schema).not.toHaveProperty("offers");
+  });
+
+  it("gives a film its runtime and a series none", () => {
+    const asFilm = buildFilmSchema(schemaSource({ kind: "film" }, [{ durationSec: 6120 }]));
+    expect(asFilm?.duration).toBe("PT1H42M");
+    // A series has no ONE runtime, and an invented average is worse than silence.
+    const asSeries = buildFilmSchema(schemaSource({}, [{ durationSec: 2700 }, { durationSec: 2800 }]));
+    expect(asSeries).not.toHaveProperty("duration");
+    expect(asSeries?.numberOfEpisodes).toBe(2);
+  });
+
+  it("is null with nothing truthful to say", () => {
+    expect(buildFilmSchema(null)).toBeNull();
+    expect(buildFilmSchema(schemaSource({ title: "   " }))).toBeNull();
+  });
+
+  it("carries no rental, session or storage field at any depth", () => {
+    // The paywall assertion is on the BYTES, not on the shape: a leak the UI
+    // happens not to render is still a leak, and this node is served to an
+    // anonymous SSR document.
+    const serialized = JSON.stringify(buildFilmSchema(schemaSource({}, [{ durationSec: 2700 }])));
+    for (const forbidden of ["hlsPrefix", "hls_prefix", "manifest", "sessionToken", "keyUrl", "rental_id"]) {
+      expect(serialized).not.toContain(forbidden);
+    }
+  });
+});