@tribe-nest/forge 3.34.0 → 3.36.0

package/src/data/queries/useFilms.ts

@@ -0,0 +1,561 @@
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import type { PaginatedData } from "../../types/models";
+
+/**
+ * Film and series rentals: the catalogue, one title, the buyer's library, and
+ * the two write legs of a rental purchase.
+ *
+ * A "film" here is a TITLE, not a video. Everything playable is an episode, and
+ * a single film is a title carrying exactly one hidden episode. That is why the
+ * detail payload always has an `episodes` array and why `primaryEpisodeId` is
+ * non-null only for `kind === "film"`: a fan renting a film never sees the word
+ * episode, but the player still plays one.
+ *
+ * Money is integer CENTS on every field that ends in `Cents`. Divide by 100
+ * exactly once, at the moment you format it, and never store the divided value.
+ */
+
+export type FilmKind = "film" | "series";
+
+/**
+ * A rental is always for a whole TITLE. There is one grain and no other.
+ *
+ * It covers every episode of the title that is available while the window runs,
+ * including episodes published mid-window, and it owns ONE clock: the clock
+ * starts at the first play of any covered episode and does not restart when the
+ * fan moves to the next one.
+ *
+ * Per-episode rental was written into the spec speculatively, nobody asked for
+ * it, and it produced a double-charge defect on the first pass. It was cut, not
+ * deferred, so there is no scope field to branch on anywhere below.
+ */
+
+/**
+ * The stored status. Note what is NOT here: `expired`.
+ *
+ * Expiry is computed from `expiresAt` at read time and surfaces as `isLive`,
+ * so nothing ever sweeps rows to expire them and a rental that ran out still
+ * reads as `active`. Ask `isLive`, never `status === "active"`, when the
+ * question is "can this person watch right now".
+ */
+export type FilmRentalStatus = "pending_payment" | "active" | "refunded" | "revoked";
+
+export interface FilmMedia {
+  id: string;
+  url: string;
+  type: string;
+  filename: string;
+}
+
+/**
+ * One window a title is sold in: a price and how long it runs.
+ *
+ * A title carries a LIST of these, so the same film can be 8 hours cheaply and
+ * 48 hours for more. The list is live options only - an archived window is
+ * absent from the payload rather than present and flagged, so nothing here can
+ * draw an offer the checkout endpoint would refuse.
+ *
+ * `id` is the whole of what checkout sends. Price and duration are resolved
+ * server-side FROM THIS ROW and are never read off the request body, which is
+ * the client-set-price defect the 2026-06-10 audit found. The numbers below
+ * exist so the fan can be told what they are buying before they buy it.
+ */
+export interface PublicFilmRentalOption {
+  id: string;
+  /** Creator's own name for the window ("Weekend pass"). Null means name it from the hours. */
+  label: string | null;
+  priceCents: number;
+  durationHours: number;
+  /** Creator's ordering. The API already sorts cheapest-first; this breaks ties. */
+  position: number;
+}
+
+/** The fields every public film payload carries, list and detail alike. */
+export interface PublicFilmBase {
+  id: string;
+  kind: FilmKind;
+  title: string;
+  slug: string;
+  description: string | null;
+  currency: string;
+  /**
+   * The windows this title is on sale in, cheapest first. Live options only.
+   *
+   * An empty array means the title is not on sale. There is no title-level price
+   * any more: `films.rental_price_cents` and `films.rental_duration_hours` were
+   * dropped, and every priced title was migrated into exactly one option.
+   */
+  rentalOptions: PublicFilmRentalOption[];
+  /** The cheapest option's price, for a catalogue card. Null when nothing is on sale. */
+  fromPriceCents: number | null;
+  publishedAt: string | null;
+  cover: FilmMedia | null;
+}
+
+export interface PublicFilmSummary extends PublicFilmBase {
+  /** Episodes a fan could actually play today (released, encoded, not archived). */
+  availableEpisodeCount: number;
+  hasFreePreview: boolean;
+}
+
+/**
+ * One playable episode as the storefront sees it.
+ *
+ * Deliberately narrow: the API builds this from an explicit public projection,
+ * so `hlsPrefix`, `renditions`, `sourceMediaId` and `transcodeError` are absent
+ * at every depth rather than present and ignored. Do not widen this type to
+ * "whatever the admin payload has" - the paywall is asserted on the bytes of
+ * this response.
+ */
+export interface PublicFilmEpisode {
+  id: string;
+  filmId: string;
+  seasonNumber: number;
+  episodeNumber: number;
+  title: string | null;
+  description: string | null;
+  durationSec: number | null;
+  /** Drip release. In the future means listed-but-not-yet-playable. */
+  availableAt: string | null;
+  /** Plays with no rental at all, but still needs a session and is still watermarked. */
+  isFreePreview: boolean;
+}
+
+/**
+ * A rental as its owner may see it.
+ *
+ * `paymentId`, `paymentProvider`, `accountId`, `profileId` and `email` are never
+ * in this payload, by construction on the server.
+ */
+export interface PublicFilmRental {
+  id: string;
+  filmId: string;
+  status: FilmRentalStatus;
+  amountCents: number;
+  currency: string;
+  /** Snapshotted at purchase, so a later admin edit cannot shorten what was sold. */
+  rentalDurationHours: number;
+  /**
+   * Which window was bought, for reporting. Null once that option is deleted.
+   *
+   * ⚠️ Not the terms. `amountCents` and `rentalDurationHours` above are the
+   * snapshot of what was actually sold, and they stand even after the option is
+   * edited or archived. Never read a price or a window back through this
+   * pointer.
+   */
+  rentalOptionId: string | null;
+  paidAt: string | null;
+  /** Shelf life: the rental must be STARTED by this instant or it lapses unwatched. */
+  startBy: string | null;
+  firstPlayedAt: string | null;
+  expiresAt: string | null;
+  refundedAt: string | null;
+  revokedAt: string | null;
+  /** The only honest answer to "can this person watch right now". */
+  isLive: boolean;
+  /** Null until first play - the clock starts then, not at purchase. */
+  msRemaining: number | null;
+  windowMs: number;
+}
+
+export interface PublicFilmDetail extends PublicFilmBase {
+  trailer: FilmMedia | null;
+  /** AVAILABLE episodes only. An unreleased one is absent, not flagged. */
+  episodes: PublicFilmEpisode[];
+  /** The one episode behind a single film. Null for a series. */
+  primaryEpisodeId: string | null;
+  /**
+   * May the offer be drawn at all?
+   *
+   * Decided by the server on the same rule that guards `POST .../rentals`: at
+   * least one live option AND at least one episode playable inside the LONGEST
+   * window a buyer could get. A published title keeps its options after every
+   * one of its episodes has failed transcode or been archived, so gating the CTA
+   * on the option list alone paints a Rent button that takes money for a stream
+   * every playback endpoint will 404.
+   */
+  canRentTitle: boolean;
+  /**
+   * The live rental this viewer holds on this title, or null.
+   *
+   * Singular, and that is now a fact about the data rather than a simplification
+   * of it: one grain means at most one live rental per (account, title), so this
+   * one row answers both the countdown and every per-episode affordance.
+   * Present only when the request carried a fan session.
+   */
+  viewerRental: PublicFilmRental | null;
+}
+
+export interface FilmCatalogPage {
+  data: PublicFilmSummary[];
+  total: number;
+  page: number;
+  limit: number;
+  /**
+   * Is the film-rentals feature switch on for this tenant?
+   *
+   * The catalogue answers 200 with an empty list rather than 404 when it is off,
+   * because `/i/films` ships to every site that takes a starter update and
+   * cannot itself be gated. Draw a "nothing here" state, not an error.
+   */
+  enabled: boolean;
+}
+
+/** Where the fan got to in one episode, under one rental. */
+export interface FilmWatchProgressEntry {
+  episodeId: string;
+  positionSec: number;
+  completedAt: string | null;
+}
+
+export interface MyFilmRental extends PublicFilmRental {
+  film: {
+    id: string;
+    title: string;
+    slug: string;
+    kind: FilmKind;
+    status: string;
+    archivedAt: string | null;
+    cover: FilmMedia | null;
+  };
+  progress: FilmWatchProgressEntry[];
+}
+
+export interface GetFilmsParams {
+  page?: number;
+  /** Server caps this at 50. */
+  limit?: number;
+  kind?: FilmKind;
+  query?: string;
+}
+
+/** The published catalogue. Public - no session needed. */
+export function useFilms(params?: GetFilmsParams, enabled = true) {
+  const { client, profileId } = useForge();
+
+  return useQuery<FilmCatalogPage>({
+    queryKey: ["films", profileId, params],
+    queryFn: async () => {
+      const res = await client.get("/public/films", {
+        params: {
+          profileId,
+          page: params?.page || 1,
+          limit: params?.limit || 20,
+          kind: params?.kind,
+          query: params?.query || undefined,
+        },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && enabled,
+  });
+}
+
+/**
+ * One title by slug, with its available episodes.
+ *
+ * `viewerRental` only comes back when the caller is signed in, so this query is
+ * keyed on the account: a fan who signs in must not keep reading the anonymous
+ * cache entry and be told they own nothing.
+ *
+ * 404s for a draft, an archived title, another tenant's slug, and while the
+ * feature switch is off. All four are the same answer on purpose - a storefront
+ * must not be able to tell "not yours" from "does not exist".
+ */
+export function useFilm(
+  slug?: string,
+  options?: { initialFilm?: PublicFilmDetail; accountId?: string; enabled?: boolean },
+) {
+  const { client, profileId } = useForge();
+
+  return useQuery<PublicFilmDetail>({
+    queryKey: ["film", profileId, slug, options?.accountId ?? null],
+    queryFn: async () => {
+      const res = await client.get(`/public/films/${slug}`, { params: { profileId } });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!slug && options?.enabled !== false,
+    initialData: options?.initialFilm,
+    retry: false,
+  });
+}
+
+/**
+ * The signed-in fan's rentals: active, not-yet-started AND expired.
+ *
+ * Expired ones are included deliberately - the library is where a fan re-rents,
+ * and a rental that vanishes on expiry reads as "you were robbed" rather than
+ * "that ended". `pending_payment` rows are excluded server-side, because an
+ * abandoned checkout is not a purchase.
+ *
+ * The buyer is resolved from the SESSION server-side; `accountId` here only
+ * gates the query on being signed in and keys the cache.
+ */
+export function useMyFilmRentals(accountId?: string, page = 1, limit = 20) {
+  const { client, profileId } = useForge();
+
+  return useQuery<PaginatedData<MyFilmRental>>({
+    queryKey: ["my-film-rentals", accountId, profileId, page, limit],
+    queryFn: async () => {
+      const res = await client.get("/public/films/my-rentals", { params: { profileId, page, limit } });
+      return res.data;
+    },
+    enabled: !!accountId && !!profileId && !!client,
+  });
+}
+
+/**
+ * Create the `pending_payment` rental for the whole title, in one chosen window.
+ *
+ * The body names WHICH window (`rentalOptionId`) and nothing else. It carries no
+ * price, no duration and no episode: both numbers are resolved server-side from
+ * the option ROW, and the body is `.strict()`, so a client that sends a price
+ * gets a 400 rather than a quietly ignored field. That is the client-set-price
+ * defect from the 2026-06-10 audit, and it costs one line to not repeat.
+ *
+ * There is no default option. Sending no `rentalOptionId` is a 400, because the
+ * alternative - silently picking one - charges somebody for a window they never
+ * chose.
+ *
+ * Idempotent in the way that matters: a second call for the same
+ * (account, film) returns the EXISTING pending rental rather than minting a
+ * second row, so a double-tapped Rent button charges once. Picking a DIFFERENT
+ * window before paying re-points that same row instead of opening a second
+ * checkout.
+ *
+ * A price of 0 comes back already `active`, with `paidAt` and `startBy` stamped
+ * and the receipt sent. Check `status` before starting a payment.
+ */
+export function useCreateFilmRental(filmId?: string) {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+
+  return useMutation<PublicFilmRental, unknown, { rentalOptionId: string }>({
+    mutationFn: async ({ rentalOptionId }) => {
+      const res = await client.post(`/public/films/${filmId}/rentals`, { profileId, rentalOptionId });
+      return res.data;
+    },
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: ["my-film-rentals"] });
+    },
+  });
+}
+
+/**
+ * Reconcile a rental with the payment provider after the return leg.
+ *
+ * Idempotent, and shared with the webhook path: whichever arrives first flips
+ * `pending_payment` to `active`, and the loser is handed the same row back
+ * untouched. Modeled as a load-time query because a return page's job is to run
+ * this exactly once on mount.
+ */
+export function useFilmRentalFinalize(filmId?: string, rentalId?: string) {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+
+  return useQuery<PublicFilmRental>({
+    queryKey: ["film-rental-finalize", profileId, filmId, rentalId],
+    queryFn: async () => {
+      const res = await client.post(`/public/films/${filmId}/rentals/${rentalId}/finalize`, { profileId });
+      void queryClient.invalidateQueries({ queryKey: ["my-film-rentals"] });
+      void queryClient.invalidateQueries({ queryKey: ["film", profileId] });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!filmId && !!rentalId,
+    retry: false,
+  });
+}
+
+/** Whole hours as a short label input, e.g. 48 -> `{ days: 2, hours: 0 }`. */
+export function splitRentalHours(hours: number): { days: number; hours: number } {
+  const safe = Number.isFinite(hours) && hours > 0 ? Math.floor(hours) : 0;
+  return { days: Math.floor(safe / 24), hours: safe % 24 };
+}
+
+/** A runtime in seconds as hours and whole minutes. Total over null and nonsense. */
+export function splitDurationSec(seconds: number | null | undefined): { hours: number; minutes: number } | null {
+  if (seconds == null || !Number.isFinite(seconds) || seconds <= 0) return null;
+  const whole = Math.floor(seconds);
+  return { hours: Math.floor(whole / 3600), minutes: Math.round((whole % 3600) / 60) };
+}
+
+/**
+ * A countdown in milliseconds as days, hours and minutes.
+ *
+ * Rounds DOWN at every level, deliberately. A window with 59 minutes left that
+ * rounds up to "1 hour" is a promise the clock will not keep, and the fan finds
+ * out at the worst possible moment.
+ */
+export function splitRemainingMs(ms: number | null | undefined): {
+  days: number;
+  hours: number;
+  minutes: number;
+  totalMinutes: number;
+} | null {
+  if (ms == null || !Number.isFinite(ms) || ms < 0) return null;
+  const totalMinutes = Math.floor(ms / 60_000);
+  return {
+    days: Math.floor(totalMinutes / 1440),
+    hours: Math.floor((totalMinutes % 1440) / 60),
+    minutes: totalMinutes % 60,
+    totalMinutes,
+  };
+}
+
+/**
+ * The windows this title is on sale in, IN THE CREATOR'S OWN ORDER.
+ *
+ * ⚠️ `position` is primary, and it has to be. The admin windows editor writes an
+ * explicit 1..N to every live row when a creator uses the up and down arrows,
+ * and the screen tells them in so many words: "Fans see these in this order, top
+ * first." The API honours it (`position asc, price_cents asc, id asc`), so a
+ * price-first re-sort here made that sentence false and made every reorder a
+ * creator ever performed invisible, since two windows on the same title almost
+ * never cost the same.
+ *
+ * Price then id break a tie, so a payload whose positions all match still lands
+ * somewhere stable rather than shuffling between renders. Sorting at all (rather
+ * than trusting the API) is for the hand-built payloads custom surfaces and
+ * fixtures pass in.
+ *
+ * "The cheapest window" is a separate question with its own answer below, and it
+ * is deliberately no longer "the first row".
+ *
+ * Total over a payload with no options at all, which is what "not on sale" looks
+ * like: an empty array, never null, so a caller can map it without a guard.
+ */
+export function filmRentalOptions(film: Pick<PublicFilmBase, "rentalOptions"> | undefined | null): PublicFilmRentalOption[] {
+  const options = film?.rentalOptions ?? [];
+  return [...options].sort((a, b) => a.position - b.position || a.priceCents - b.priceCents || a.id.localeCompare(b.id));
+}
+
+/**
+ * The window a fan gets if they never open the picker.
+ *
+ * The cheapest one, deliberately. Pre-selecting anything dearer would make the
+ * default choice the one that costs more, which is a decision the fan did not
+ * make. Null when the title is not on sale.
+ *
+ * ⚠️ Computed as an explicit minimum over the price, NOT as the first row of the
+ * list above: that list is ordered by the creator's hand, so index 0 is whatever
+ * window they chose to show first. Ties fall to the earlier row, which is the
+ * creator's ordering deciding between two identically priced windows.
+ */
+export function cheapestFilmRentalOption(
+  film: Pick<PublicFilmBase, "rentalOptions"> | undefined | null,
+): PublicFilmRentalOption | null {
+  return filmRentalOptions(film).reduce<PublicFilmRentalOption | null>(
+    (cheapest, option) => (cheapest === null || option.priceCents < cheapest.priceCents ? option : cheapest),
+    null,
+  );
+}
+
+/**
+ * The number a catalogue card prints, in cents, or null when nothing is on sale.
+ *
+ * Prefers the server's own `fromPriceCents` and falls back to the cheapest
+ * option, so a summary payload and a hand-built one answer the same. A price of
+ * 0 is a real (free) window somebody chose to publish, so every check here is
+ * `!= null`, never truthiness.
+ */
+export function filmFromPriceCents(
+  film: (Partial<Pick<PublicFilmBase, "fromPriceCents">> & Pick<PublicFilmBase, "rentalOptions">) | undefined | null,
+): number | null {
+  if (!film) return null;
+  if (film.fromPriceCents != null) return film.fromPriceCents;
+  return cheapestFilmRentalOption(film)?.priceCents ?? null;
+}
+
+/**
+ * Is this episode released yet?
+ *
+ * The API already omits unreleased episodes from the public detail payload, so
+ * in practice this only matters for an episode read out of a cached page that
+ * crossed its own release moment. Total over a missing/garbage timestamp:
+ * anything unparseable counts as released, matching the server's
+ * `available_at IS NULL` arm.
+ */
+export function isFilmEpisodeReleased(
+  episode: Pick<PublicFilmEpisode, "availableAt">,
+  now: Date = new Date(),
+): boolean {
+  if (!episode.availableAt) return true;
+  const at = new Date(episode.availableAt).getTime();
+  if (!Number.isFinite(at)) return true;
+  return at <= now.getTime();
+}
+
+/**
+ * Does this rental cover this episode?
+ *
+ * The client-side twin of the server's coverage clause, for drawing affordances
+ * only. It is NOT the entitlement: every playback endpoint re-derives coverage
+ * from the database on every request, so being wrong here draws a button that
+ * 404s rather than granting anything.
+ *
+ * One grain means one question: a rental covers every episode of its own title
+ * and nothing else. A free preview short-circuits to true with no rental at all,
+ * and it short-circuits COVERAGE only. Playability is a separate question, and
+ * an unreleased preview is still not playable.
+ */
+export function filmRentalCoversEpisode(
+  rental: Pick<PublicFilmRental, "filmId"> | null | undefined,
+  episode: Pick<PublicFilmEpisode, "id" | "filmId" | "isFreePreview">,
+): boolean {
+  if (episode.isFreePreview) return true;
+  if (!rental) return false;
+  return rental.filmId === episode.filmId;
+}
+
+/**
+ * May this viewer press play on this episode right now?
+ *
+ * Three things have to be true at once, and the reason they are answered
+ * together is that the two ways of getting them apart both strand somebody: a
+ * covered-but-expired rental drawing Watch sends a fan to a 404, and an
+ * unreleased episode drawing Watch does the same on a drip series.
+ *
+ * Free previews need no rental. Everything else needs a LIVE one on this title.
+ */
+export function canWatchFilmEpisode(
+  rental: Pick<PublicFilmRental, "filmId" | "isLive"> | null | undefined,
+  episode: Pick<PublicFilmEpisode, "id" | "filmId" | "isFreePreview" | "availableAt">,
+  now: Date = new Date(),
+): boolean {
+  if (!isFilmEpisodeReleased(episode, now)) return false;
+  if (episode.isFreePreview) return true;
+  return !!rental?.isLive && rental.filmId === episode.filmId;
+}
+
+/** Episodes grouped by season, seasons and episodes both in ascending order. */
+export function groupFilmEpisodesBySeason(
+  episodes: PublicFilmEpisode[],
+): { seasonNumber: number; episodes: PublicFilmEpisode[] }[] {
+  const seasons = new Map<number, PublicFilmEpisode[]>();
+  for (const episode of episodes) {
+    const bucket = seasons.get(episode.seasonNumber);
+    if (bucket) bucket.push(episode);
+    else seasons.set(episode.seasonNumber, [episode]);
+  }
+  return [...seasons.entries()]
+    .sort((a, b) => a[0] - b[0])
+    .map(([seasonNumber, list]) => ({
+      seasonNumber,
+      episodes: [...list].sort((a, b) => a.episodeNumber - b.episodeNumber),
+    }));
+}
+
+/**
+ * The episode after this one, in season-then-number order, or null at the end.
+ *
+ * Used for the next-episode prompt. Only ever picks from the AVAILABLE episodes
+ * the API returned, so a series still releasing weekly correctly ends at the
+ * last one out rather than offering a link to nothing.
+ */
+export function nextFilmEpisode(episodes: PublicFilmEpisode[], currentEpisodeId: string): PublicFilmEpisode | null {
+  const ordered = groupFilmEpisodesBySeason(episodes).flatMap((season) => season.episodes);
+  const index = ordered.findIndex((episode) => episode.id === currentEpisodeId);
+  if (index < 0 || index === ordered.length - 1) return null;
+  return ordered[index + 1] ?? null;
+}

package/src/data/queries/usePaymentFlow.ts

@@ -63,10 +63,32 @@ export function usePaymentFlow(opts: UsePaymentFlowOptions) {
     onError: opts.onPaystackError,
   };
 
+  /**
+   * The return URL the charge was actually STARTED with.
+   *
+   * Click-driven flows (event tickets, courses, coaching, offers) build their
+   * finalise URL from an id that does not exist until the resource is created,
+   * so they pass it in the `start()` override and never as a hook option. The
+   * Paystack session was read from the OPTION alone, so for all four it was
+   * `undefined`: the fan paid, the popup closed, `openPaystackCheckout` had
+   * nowhere to send them, and they sat on the checkout they had just paid on
+   * with no receipt and no confirmation. The charge was fine every time; only
+   * the way back was missing. Stripe was unaffected because it hands its own
+   * `return_url` to `confirmPayment`.
+   *
+   * A ref rather than state: it is read when the popup is opened, never
+   * rendered, and a re-render on every start would re-run the auto-open effect.
+   */
+  const startedReturnUrlRef = useRef<string | undefined>(undefined);
+
   const mutation = useMutation<PaymentFlowResult, unknown, Record<string, unknown> | undefined>({
     mutationFn: async (override) => {
       // override wins — click-driven flows pass a just-created orderId/returnUrl.
-      const res = await client.post(path as string, { ...body, profileId, returnUrl, ...(override ?? {}) });
+      const payload = { ...body, profileId, returnUrl, ...(override ?? {}) };
+      // Whatever the server was told, byte for byte. Resolving it any other way
+      // is how these two drift apart again.
+      startedReturnUrlRef.current = (payload.returnUrl as string | undefined) || undefined;
+      const res = await client.post(path as string, payload);
       const data = res.data as PaymentStartResponse;
       const provider = (data.paymentProvider ?? data.paymentProviderName) as PaymentProviderName | undefined;
       return { ...data, provider };
@@ -88,8 +110,11 @@ export function usePaymentFlow(opts: UsePaymentFlowOptions) {
    * session, which is what makes "closed it by accident" recoverable.
    */
   const openPaystack = useCallback(async (): Promise<PaystackCheckoutOutcome> => {
-    if (!hasPaystackSession(session)) return "unavailable";
-    return openPaystackCheckout(session, {
+    // The URL the charge was started with wins over the static option: for a
+    // click-driven flow it is the only one there has ever been.
+    const active = { ...session, returnUrl: startedReturnUrlRef.current ?? session.returnUrl };
+    if (!hasPaystackSession(active)) return "unavailable";
+    return openPaystackCheckout(active, {
       onSuccess: handlersRef.current.onSuccess,
       onDismiss: handlersRef.current.onDismiss,
       onError: handlersRef.current.onError,