@tribe-nest/forge 3.34.0 → 3.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.34.0",
+  "version": "3.35.0",
   "publishConfig": {
     "access": "public"
   },
@@ -21,7 +21,8 @@
     "prepack": "npm run build:css",
     "check-types": "tsc --noEmit",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "lint": "eslint ."
   },
   "dependencies": {
     "@paystack/inline-js": "^2.24.0",

package/src/client/_tests/tenantHeaders.spec.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect } from "vitest";
+import type { AxiosRequestConfig } from "axios";
+
+import { createForgeClient } from "../createForgeClient";
+
+/**
+ * WHICH site is asking, on every request.
+ *
+ * A profile can own several websites, and a deploy could only ever say whose
+ * tenant it belonged to, never which of that tenant's sites it was. Everything
+ * derived from the tenant alone therefore named the profile's PRIMARY site: a
+ * canonical URL, a share link, a link the backend puts in an email. The site
+ * serving the page and the site named in the link were different sites, and
+ * nothing errored.
+ *
+ * A header rather than a parameter because the fact is ambient: it is true of
+ * every request this deploy makes, so it cannot be forgotten by the next
+ * endpoint somebody adds.
+ */
+function capture(options: Parameters<typeof createForgeClient>[0]) {
+  const sent: AxiosRequestConfig[] = [];
+  const client = createForgeClient(options);
+  // The request interceptor has already run by the time the adapter is called,
+  // so what lands here is what would have gone over the wire.
+  client.defaults.adapter = async (config) => {
+    sent.push(config);
+    return { data: {}, status: 200, statusText: "OK", headers: {}, config } as never;
+  };
+  return { client, sent };
+}
+
+const BASE = { baseURL: "https://api.example.test" };
+
+describe("tenant identity headers", () => {
+  it("sends which website and which profile on every request", async () => {
+    const { client, sent } = capture({ ...BASE, websiteId: "web-1", profileId: "prof-1" });
+
+    await client.get("/public/anything");
+    await client.post("/public/something-else", {});
+
+    expect(sent).toHaveLength(2);
+    for (const config of sent) {
+      expect(config.headers?.["x-website-id"]).toBe("web-1");
+      expect(config.headers?.["x-profile-id"]).toBe("prof-1");
+    }
+  });
+
+  it("omits each header when the deploy does not know that value", async () => {
+    // A preview built from a bare profile has no website, and an older bundle
+    // has neither. Sending an empty header would make "unknown" and "empty
+    // string" indistinguishable to the server.
+    const { client, sent } = capture({ ...BASE, profileId: "prof-1" });
+
+    await client.get("/public/anything");
+
+    expect(sent[0]!.headers?.["x-profile-id"]).toBe("prof-1");
+    expect(sent[0]!.headers?.["x-website-id"]).toBeUndefined();
+  });
+
+  it("sends neither when the client is created without them", async () => {
+    const { client, sent } = capture(BASE);
+
+    await client.get("/public/anything");
+
+    expect(sent[0]!.headers?.["x-website-id"]).toBeUndefined();
+    expect(sent[0]!.headers?.["x-profile-id"]).toBeUndefined();
+  });
+
+  it("does not disturb the headers that already ride every request", async () => {
+    const { client, sent } = capture({ ...BASE, websiteId: "web-1", publishableKey: "pk_site_abc" });
+
+    await client.get("/public/anything");
+
+    expect(sent[0]!.headers?.["x-forge-key"]).toBe("pk_site_abc");
+    expect(sent[0]!.headers?.["x-timezone-offset"]).toBeDefined();
+  });
+});

package/src/client/createForgeClient.ts

@@ -32,6 +32,29 @@ export interface ForgeClientOptions {
    * place (Component 1) this is sent on every request to scope reads to the tenant.
    */
   publishableKey?: string;
+  /**
+   * WHICH SITE this deploy is, sent as `x-website-id` on every request.
+   *
+   * A profile can own several websites, and until now a running site could not
+   * say which of them it was: the only tenant identity it carried was the
+   * profile's. Everything derived from that named the profile's primary site
+   * instead of the one serving the page, which is wrong for a canonical URL, a
+   * share link, or a link the backend puts in an email.
+   *
+   * Sent as a HEADER rather than threaded through call sites because it is
+   * ambient: it is true of every request this deploy makes, and a header cannot
+   * be forgotten by the next endpoint somebody adds.
+   */
+  websiteId?: string;
+  /**
+   * The tenant, sent as `x-profile-id`.
+   *
+   * Redundant today with `x-forge-key` where a publishable key is issued, and
+   * with the subdomain the request already arrives on. It rides along because
+   * neither of those is present on every deploy yet, and a request that cannot
+   * name its tenant is one the server has to infer it for.
+   */
+  profileId?: string;
   /** Enable 401-triggered refresh-and-retry for this client's auth lane. */
   refresh?: ForgeClientRefreshOptions;
 }
@@ -47,6 +70,8 @@ export const createForgeClient = ({
   baseURL,
   getToken,
   publishableKey,
+  websiteId,
+  profileId,
   refresh,
 }: ForgeClientOptions): AxiosInstance => {
   const client = axios.create({ baseURL });
@@ -62,6 +87,18 @@ export const createForgeClient = ({
       config.headers["x-forge-key"] = publishableKey;
     }
 
+    // Who this deploy is. Baked at publish, so they are the same on every
+    // request and cannot be spoofed into naming a tenant this site is not:
+    // the server still decides what a caller may see, and these only say which
+    // site is asking.
+    if (websiteId) {
+      config.headers["x-website-id"] = websiteId;
+    }
+
+    if (profileId) {
+      config.headers["x-profile-id"] = profileId;
+    }
+
     // First-touch funnel attribution. Rides every request rather than every
     // capture call, so a lead that arrives through a booking or a checkout is
     // attributed the same as one that arrives through a form.

package/src/data/queries/useFilmPlaybackSession.ts

@@ -0,0 +1,224 @@
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation } from "@tanstack/react-query";
+
+/**
+ * The three write legs of watching an episode: open a session, keep it alive,
+ * and record where the fan got to.
+ *
+ * Everything load-bearing about protection is on the server and re-derived on
+ * every single request - the rental, the session holder and the token's episode
+ * binding are all re-checked when the key is fetched. Nothing in this file is a
+ * gate. It is the client half of a conversation whose answers are authoritative.
+ */
+
+/** What the viewer overlay draws. Not a credential: it identifies, it does not authorize. */
+export interface FilmWatermarkPayload {
+  name: string;
+  email: string;
+  /** Short reference tying a leak to a TRANSACTION, not just to an address someone could fake. */
+  rentalRef: string;
+}
+
+export interface FilmPlaybackEpisodeInfo {
+  id: string;
+  filmId: string;
+  seasonNumber: number;
+  episodeNumber: number;
+  title: string | null;
+  durationSec: number | null;
+  isFreePreview: boolean;
+}
+
+export interface FilmPlaybackRentalInfo {
+  id: string;
+  firstPlayedAt: string | null;
+  expiresAt: string | null;
+  durationHours: number;
+}
+
+/**
+ * One sidecar WebVTT track, as the session hands it over.
+ *
+ * `url` is ABSOLUTE and carries NO token, exactly like `masterUrl`. The token is
+ * appended by whoever renders the `<track>`, from whatever they hold at that
+ * moment, because the heartbeat rotates it: a token baked in server-side would
+ * be stale within ten minutes, and appending a second one would produce
+ * `?st=a&st=b`, which Express parses as an array and the schema rejects.
+ *
+ * Live tracks only. An archived one is absent rather than flagged, so no
+ * `<track>` can point at a 404.
+ */
+export interface FilmSubtitleTrack {
+  id: string;
+  /** Canonical BCP-47, e.g. `en`, `pt-BR`, `zh-Hans`. Goes straight into `srclang`. */
+  language: string;
+  /** What the track picker shows. Never blank: the server falls back to the language tag. */
+  label: string;
+  isDefault: boolean;
+  url: string;
+}
+
+export interface FilmPlaybackSession {
+  sessionId: string;
+  /**
+   * Short-lived (~10 min), bound to `{rentalId, episodeId, sessionId}`, and
+   * refreshed by the heartbeat. It travels as `?st=` because HLS players cannot
+   * set headers on their own segment and key requests.
+   */
+  sessionToken: string;
+  /** Master playlist. Absolute when the API knows its own URL, root-relative otherwise. */
+  masterUrl: string;
+  keyUrl: string;
+  /** Sidecar WebVTT tracks, `isDefault` first then by language. Empty is normal. */
+  subtitles: FilmSubtitleTrack[];
+  watermark: FilmWatermarkPayload;
+  /** End of the rental window. Null for a free preview, which has no rental. */
+  expiresAt: string | null;
+  /** True only for the call that STARTED the window. Say so on screen: this is decision 12. */
+  clockStartedNow: boolean;
+  resumeAtSec: number;
+  heartbeatIntervalSec: number;
+  episode: FilmPlaybackEpisodeInfo;
+  /** Null for a free preview. */
+  rental: FilmPlaybackRentalInfo | null;
+}
+
+export interface FilmHeartbeatResult {
+  sessionId: string;
+  /** A FRESH token. The old one keeps working until its own expiry. */
+  sessionToken: string;
+  expiresAt: string | null;
+  heartbeatIntervalSec: number;
+}
+
+export interface FilmProgressResult {
+  /** False for a free preview: progress is keyed by rental and a preview has none. */
+  recorded: boolean;
+  positionSec: number;
+  completed: boolean;
+}
+
+/** Status off an axios-ish rejection, without importing axios or trusting its shape. */
+export const filmErrorStatus = (error: unknown): number | null => {
+  const status = (error as { response?: { status?: unknown } } | null | undefined)?.response?.status;
+  return typeof status === "number" ? status : null;
+};
+
+/** The API's machine-readable reason, when it sent one. */
+export const filmErrorCode = (error: unknown): string | null => {
+  const code = (error as { response?: { data?: { code?: unknown } } } | null | undefined)?.response?.data?.code;
+  return typeof code === "string" && code ? code : null;
+};
+
+/** The API's already-translated sentence, when it sent one. */
+export const filmErrorMessage = (error: unknown): string | null => {
+  const message = (error as { response?: { data?: { message?: unknown } } } | null | undefined)?.response?.data
+    ?.message;
+  return typeof message === "string" && message.trim() ? message : null;
+};
+
+/**
+ * Another session took this rental over.
+ *
+ * One active session per rental, and a NEW session wins - takeover rather than
+ * rejection, so a crashed tab never locks the buyer out of what they paid for.
+ * The tab that lost is the one that gets this, and the honest thing to tell that
+ * person is "this is playing somewhere else", not "your rental is invalid".
+ */
+export const FILM_SESSION_TAKEN_OVER = "FILM_SESSION_TAKEN_OVER";
+
+/**
+ * The Redis holder lapsed - nobody took over, this tab simply stopped
+ * heartbeating (backgrounded, asleep, offline). Recoverable by opening a new
+ * session, and it must NOT be drawn as "playing on another device", which would
+ * be a lie the fan would act on.
+ */
+export const FILM_SESSION_EXPIRED = "FILM_SESSION_EXPIRED";
+
+const playbackBase = (filmId: string, episodeId: string) => `/public/films/${filmId}/episodes/${episodeId}`;
+
+/**
+ * Open a playback session for one episode.
+ *
+ * Takes over any existing session FOR THAT RENTAL, including one on a different
+ * episode: the cap is one stream per rental, so switching from episode 1 to
+ * episode 2 replaces the session rather than opening a second one.
+ *
+ * The first successful call against any covered episode also starts the rental
+ * clock, and says so via `clockStartedNow`.
+ */
+export function useCreateFilmPlaybackSession(filmId?: string, episodeId?: string) {
+  const { client } = useForge();
+
+  return useMutation<FilmPlaybackSession, unknown, void>({
+    mutationFn: async () => {
+      const res = await client.post(`${playbackBase(filmId as string, episodeId as string)}/playback-sessions`, {});
+      return res.data;
+    },
+  });
+}
+
+/**
+ * Keep the session alive and discover a takeover.
+ *
+ * Both halves matter. An AES-128 player fetches the key once per playlist, so
+ * without this the Redis holder would lapse mid-film on a long episode; and a
+ * displaced tab has no other way to learn it was displaced, because nothing
+ * pushes to it.
+ */
+export function useFilmPlaybackHeartbeat(filmId?: string, episodeId?: string) {
+  const { client } = useForge();
+
+  return useMutation<FilmHeartbeatResult, unknown, { sessionToken: string }>({
+    mutationFn: async ({ sessionToken }) => {
+      const res = await client.post(
+        `${playbackBase(filmId as string, episodeId as string)}/playback-sessions/heartbeat`,
+        { sessionToken },
+      );
+      return res.data;
+    },
+  });
+}
+
+/**
+ * Record the resume position.
+ *
+ * Never trusted for entitlement, only for continue-watching and for the
+ * next-episode prompt, which is why it is safe to debounce hard and to drop
+ * silently on failure.
+ */
+export function useRecordFilmProgress(filmId?: string, episodeId?: string) {
+  const { client } = useForge();
+
+  return useMutation<FilmProgressResult, unknown, { sessionToken: string; positionSec: number; completed?: boolean }>({
+    mutationFn: async (body) => {
+      const res = await client.put(`${playbackBase(filmId as string, episodeId as string)}/progress`, body);
+      return res.data;
+    },
+  });
+}
+
+/**
+ * Turn a URL the API handed back into one this browser can fetch.
+ *
+ * The API returns a ROOT-RELATIVE path when it does not know its own public URL,
+ * and a root-relative path on a creator site resolves against the CREATOR's
+ * origin, not the API's. Left alone that produces a 404 on the site's own router
+ * rather than a manifest, which reads as "the player is broken".
+ */
+export function absolutizeFilmUrl(url: string, apiUrl: string): string {
+  if (/^https?:\/\//i.test(url)) return url;
+  const base = apiUrl.replace(/\/+$/, "");
+  return `${base}${url.startsWith("/") ? "" : "/"}${url}`;
+}
+
+/**
+ * Attach the session token to a playback URL.
+ *
+ * `st` is the primary carrier because an HLS engine fetches manifests, keys and
+ * segments itself and cannot be made to send a header on those requests.
+ */
+export function withFilmSessionToken(url: string, sessionToken: string): string {
+  const separator = url.includes("?") ? "&" : "?";
+  return `${url}${separator}st=${encodeURIComponent(sessionToken)}`;
+}