@tribe-nest/forge 3.34.0 → 3.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.34.0",
+  "version": "3.36.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/_tests/paymentFlowReturnUrl.spec.tsx

@@ -0,0 +1,165 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { ReactNode } from "react";
+
+/**
+ * The way back from a Paystack payment.
+ *
+ * Four checkouts (event tickets, courses, coaching, offers) build their finalise
+ * URL from an id that does not exist until the resource is created, so they hand
+ * it to `start({ …, returnUrl })` and never as a hook option. The Paystack
+ * session was assembled from the OPTION alone, so for all four it carried no
+ * return URL: the buyer paid, the popup closed, and the helper had nowhere to
+ * send them. They were left sitting on the checkout they had just paid on, with
+ * no receipt, no confirmation and no error — while the charge itself succeeded
+ * every time.
+ *
+ * Stripe never had this: it hands its own `return_url` to `confirmPayment`.
+ *
+ * The real helper is in the path here, with only `@paystack/inline-js` faked, so
+ * this asserts the navigation a fan actually gets rather than what was passed
+ * between two of our own functions.
+ */
+
+type ResumeOptions = {
+  onSuccess?: (t: { reference?: string }) => void;
+  onCancel?: () => void;
+  onLoad?: (r: unknown) => void;
+  onError?: (e: unknown) => void;
+};
+
+let captured: ResumeOptions = {};
+
+vi.mock("@paystack/inline-js", () => ({
+  default: class FakePaystackPop {
+    resumeTransaction(_accessCode: string, options: ResumeOptions = {}) {
+      captured = options;
+      options.onLoad?.({});
+      return {};
+    }
+    cancelTransaction() {}
+  },
+}));
+
+const post = vi.fn();
+
+vi.mock("../../../provider/ForgeProvider", () => ({
+  useForge: () => ({ client: { post }, profileId: "profile-1" }),
+}));
+
+import { usePaymentFlow } from "../usePaymentFlow";
+
+const FINALISE = "https://artist.test/i/events/summer-show/finalise?orderId=order-1";
+
+const wrapper = ({ children }: { children: ReactNode }) => {
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false }, mutations: { retry: false } } });
+  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
+};
+
+let location: { href: string };
+
+beforeEach(() => {
+  captured = {};
+  post.mockReset();
+  post.mockResolvedValue({
+    data: { paymentProvider: "paystack", accessCode: "ac_1", checkoutUrl: "https://checkout.paystack.com/ac_1" },
+  });
+  location = { href: "https://artist.test/i/events/summer-show" };
+  Object.defineProperty(window, "location", { value: location, writable: true, configurable: true });
+});
+
+/** A ticket checkout: nothing is known until the order exists, so nothing is static. */
+const useClickDrivenFlow = () => usePaymentFlow({ path: "/public/events/event-1/start-payment", autoStart: false });
+
+/**
+ * Pay in the popup the flow opened for itself.
+ *
+ * `usePaymentFlow` auto-opens once a charge lands, which is what the ticket
+ * checkout relies on ("Paystack redirected" is its whole payment step), so the
+ * spec waits for that rather than racing it with a hand-driven open.
+ */
+async function payInPopup(reference = "pay-uuid"): Promise<void> {
+  await waitFor(() => expect(captured.onSuccess).toBeTypeOf("function"));
+  await act(async () => {
+    captured.onSuccess?.({ reference });
+  });
+}
+
+describe("usePaymentFlow: returning from a Paystack payment", () => {
+  it("REGRESSION: sends the buyer to the finalise URL the charge was started with", async () => {
+    const { result } = renderHook(useClickDrivenFlow, { wrapper });
+
+    await act(async () => {
+      await result.current.start({ orderId: "order-1", returnUrl: FINALISE });
+    });
+
+    // The server was told where to come back to...
+    expect(post).toHaveBeenCalledWith(
+      "/public/events/event-1/start-payment",
+      expect.objectContaining({ orderId: "order-1", returnUrl: FINALISE }),
+    );
+
+    await payInPopup();
+
+    // ...and so is the buyer. Before this fix `location.href` never moved.
+    expect(location.href).toContain("/finalise");
+    expect(location.href).toContain("orderId=order-1");
+    // The two params every finalise page already reads off a hosted redirect.
+    expect(location.href).toContain("reference=pay-uuid");
+    expect(location.href).toContain("trxref=pay-uuid");
+  });
+
+  it("still honours a static returnUrl for the flows that have one up front", async () => {
+    // The cart, film rentals and payment links pass it as an option, and that
+    // path must not regress while the click-driven one is fixed.
+    const { result } = renderHook(
+      () => usePaymentFlow({ path: "/public/payment-links/link-1/start-payment", returnUrl: FINALISE, autoStart: false }),
+      { wrapper },
+    );
+
+    await act(async () => {
+      await result.current.start();
+    });
+    await payInPopup();
+
+    expect(location.href).toContain("reference=pay-uuid");
+  });
+
+  it("leaves navigation alone when the surface finalises in place", async () => {
+    // Donations show their own thank-you step, so they pass `onPaystackSuccess`
+    // and must NOT be navigated away from it.
+    const onPaystackSuccess = vi.fn();
+    const { result } = renderHook(
+      () =>
+        usePaymentFlow({ path: "/public/donations/d-1/start-payment", autoStart: false, onPaystackSuccess }),
+      { wrapper },
+    );
+
+    await act(async () => {
+      await result.current.start({ returnUrl: FINALISE });
+    });
+    await payInPopup();
+
+    expect(onPaystackSuccess).toHaveBeenCalledWith({ reference: "pay-uuid" });
+    expect(location.href).toBe("https://artist.test/i/events/summer-show");
+  });
+
+  it("carries the LATEST start's URL when a charge is re-minted", async () => {
+    // A discount code re-starts the charge. Sending the buyer to the first
+    // attempt's finalise page would land them on a different order.
+    const { result } = renderHook(useClickDrivenFlow, { wrapper });
+
+    await act(async () => {
+      await result.current.start({ orderId: "order-1", returnUrl: "https://artist.test/finalise?orderId=order-1" });
+    });
+    await act(async () => {
+      await result.current.start({ orderId: "order-2", returnUrl: "https://artist.test/finalise?orderId=order-2" });
+    });
+    await payInPopup();
+
+    expect(location.href).toContain("orderId=order-2");
+    expect(location.href).not.toContain("orderId=order-1");
+  });
+});

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)}`;
+}