@tribe-nest/forge 3.21.0 → 3.23.0

package/src/ui/format/_tests/ticketAvailability.spec.ts

@@ -0,0 +1,283 @@
+import { describe, it, expect } from "vitest";
+import type { ITicket } from "../../../types/models";
+import {
+  formatOnSaleAt,
+  isTicketScheduled,
+  maxAddableTickets,
+  onSaleBadge,
+  onSaleNotice,
+  ticketSaleWindow,
+  ticketSeatLabel,
+  ticketSeatNotice,
+  ticketSeatState,
+  ticketSeatsAvailable,
+  ticketSeatsUnsold,
+} from "../ticketAvailability";
+
+/**
+ * The availability arithmetic shared by BOTH storefront stacks (Forge and the
+ * legacy `apps/client`). It is shared rather than written twice precisely so the
+ * two cannot drift from each other or from the server — these tests pin the
+ * behaviour they both depend on.
+ *
+ * The two numbers that must match the server exactly:
+ *
+ *  - `quantity - sold - held`, the predicate in `inventoryHold.ts`, and
+ *  - `now < availableFrom`, the `not_yet_on_sale` branch of
+ *    `evaluateTierSellability`.
+ *
+ * Every case below is written as the buyer's screen versus the server's answer,
+ * because a disagreement between them is the whole defect class.
+ */
+
+const tier = (over: Partial<ITicket> = {}): ITicket => ({
+  id: over.id ?? "t1",
+  title: "GA",
+  description: "",
+  price: 20,
+  quantity: 100,
+  order: 0,
+  sold: 0,
+  maxPerPerson: 10,
+  ...over,
+});
+
+/** The predicate `services/_core/inventoryHold.ts` actually runs. */
+const serverWouldSell = (t: ITicket, n: number) => t.quantity - t.sold - (t.held ?? 0) >= n;
+
+describe("ticketSeatsAvailable", () => {
+  it("subtracts held, which is what the server sells on", () => {
+    expect(ticketSeatsAvailable(tier({ quantity: 10, sold: 5, held: 3 }))).toBe(2);
+  });
+
+  it("treats an ABSENT held as zero, so an older API build is unchanged", () => {
+    // The column is published by `PUBLIC_TICKET_COLUMNS`, but a site pinned to
+    // a build that predates the hold engine must keep its old behaviour rather
+    // than read every tier as sold out.
+    expect(ticketSeatsAvailable(tier({ quantity: 10, sold: 5 }))).toBe(5);
+  });
+
+  it("never goes negative, so an oversold tier reads as zero not as a negative cap", () => {
+    expect(ticketSeatsAvailable(tier({ quantity: 10, sold: 9, held: 4 }))).toBe(0);
+  });
+
+  it("is exactly the server's predicate — the bug, stated as an assertion", () => {
+    // The reported case: the storefront said "3 left", the server said no.
+    const rush = tier({ quantity: 10, sold: 7, held: 3 });
+    expect(rush.quantity - rush.sold).toBe(3); // what the old UI showed
+    expect(ticketSeatsAvailable(rush)).toBe(0); // what the server means
+    expect(serverWouldSell(rush, 1)).toBe(false);
+  });
+
+  it("agrees with the server at every quantity across the boundary", () => {
+    const t = tier({ quantity: 10, sold: 6, held: 2 });
+    for (let n = 1; n <= 5; n += 1) {
+      expect(n <= ticketSeatsAvailable(t)).toBe(serverWouldSell(t, n));
+    }
+  });
+});
+
+describe("ticketSeatsUnsold", () => {
+  it("ignores held — it is the waitlist's question, not the buy button's", () => {
+    expect(ticketSeatsUnsold(tier({ quantity: 10, sold: 7, held: 3 }))).toBe(3);
+  });
+});
+
+describe("ticketSeatState", () => {
+  it("is available while a seat is genuinely free", () => {
+    expect(ticketSeatState(tier({ quantity: 10, sold: 5, held: 3 }))).toBe("available");
+  });
+
+  it("separates seats in other carts from seats that are gone", () => {
+    // Both are un-addable. They are NOT the same sentence: one comes back.
+    expect(ticketSeatState(tier({ quantity: 10, sold: 7, held: 3 }))).toBe("reserved_elsewhere");
+    expect(ticketSeatState(tier({ quantity: 10, sold: 10, held: 0 }))).toBe("sold_out");
+  });
+
+  it("calls a fully-sold tier sold out even when a hold is also outstanding", () => {
+    // Nothing left to release, so there is no "check back in a few minutes".
+    expect(ticketSeatState(tier({ quantity: 10, sold: 10, held: 2 }))).toBe("sold_out");
+  });
+});
+
+describe("ticketSeatLabel / ticketSeatNotice", () => {
+  it("gives the stepper a short word only when the tier cannot be added", () => {
+    expect(ticketSeatLabel("available")).toBeNull();
+    expect(ticketSeatLabel("reserved_elsewhere")).toBe("ON HOLD");
+    expect(ticketSeatLabel("sold_out")).toBe("SOLD OUT");
+  });
+
+  it("explains only the state a fan should wait out", () => {
+    expect(ticketSeatNotice("available")).toBeNull();
+    // A sold-out tier gets the waitlist, not a "check back" — that is what
+    // `isTicketSoldOut` in useEventWaitlist draws, and two prompts would fight.
+    expect(ticketSeatNotice("sold_out")).toBeNull();
+    expect(ticketSeatNotice("reserved_elsewhere")).toMatch(/someone else's checkout/);
+  });
+});
+
+describe("ticketSaleWindow", () => {
+  const now = new Date("2026-08-05T12:00:00.000Z");
+
+  it("is open when no on-sale time is set — every tier that predates the field", () => {
+    expect(ticketSaleWindow(tier(), now)).toEqual({ status: "open" });
+    expect(ticketSaleWindow(tier({ availableFrom: null }), now)).toEqual({ status: "open" });
+  });
+
+  it("is scheduled while the on-sale time is in the future", () => {
+    const w = ticketSaleWindow(tier({ availableFrom: "2026-08-07T09:00:00.000Z" }), now);
+    expect(w.status).toBe("scheduled");
+    expect(w.status === "scheduled" && w.startsAt.toISOString()).toBe("2026-08-07T09:00:00.000Z");
+  });
+
+  it("opens ON the boundary second, matching the server's strict `now < availableFrom`", () => {
+    // A storefront that allowed the boundary would produce the one refusal this
+    // module exists to prevent; one that refused it would hold the door shut a
+    // second past the announced time in a rush. Both matter.
+    const at = "2026-08-05T12:00:00.000Z";
+    expect(ticketSaleWindow(tier({ availableFrom: at }), now)).toEqual({ status: "open" });
+    expect(ticketSaleWindow(tier({ availableFrom: at }), new Date(Date.parse(at) - 1)).status).toBe(
+      "scheduled",
+    );
+  });
+
+  it("falls open on an unparseable value rather than locking the tier forever", () => {
+    // Failing closed here would make a bad string an unsellable tier with no
+    // explanation on screen. The server is the guard either way.
+    expect(ticketSaleWindow(tier({ availableFrom: "not a date" }), now)).toEqual({ status: "open" });
+  });
+
+  it("isTicketScheduled is the same verdict as a boolean", () => {
+    expect(isTicketScheduled(tier({ availableFrom: "2026-08-07T09:00:00.000Z" }), now)).toBe(true);
+    expect(isTicketScheduled(tier({ availableFrom: "2026-08-01T09:00:00.000Z" }), now)).toBe(false);
+    expect(isTicketScheduled(tier(), now)).toBe(false);
+  });
+});
+
+describe("on-sale copy", () => {
+  const startsAt = new Date("2026-08-07T09:00:00.000Z");
+
+  it("counts down under the hour, where the clock beats the calendar", () => {
+    const now = new Date(startsAt.getTime() - 12 * 60_000);
+    expect(onSaleBadge(startsAt, now)).toBe("On sale in 12 minutes");
+  });
+
+  it("does not say '1 minutes'", () => {
+    expect(onSaleBadge(startsAt, new Date(startsAt.getTime() - 60_000))).toBe("On sale in 1 minute");
+  });
+
+  it("rounds a part-minute UP, so it never announces zero while still shut", () => {
+    // `Math.floor` here would render "On sale in 0 minutes" beside a disabled
+    // button for a whole minute.
+    expect(onSaleBadge(startsAt, new Date(startsAt.getTime() - 30_000))).toBe("On sale in 1 minute");
+  });
+
+  it("switches to the absolute time at an hour and above", () => {
+    const now = new Date(startsAt.getTime() - 61 * 60_000);
+    expect(onSaleBadge(startsAt, now)).toBe(`On sale ${formatOnSaleAt(startsAt)}`);
+  });
+
+  it("says 'on sale now' once the instant has passed, never a negative countdown", () => {
+    expect(onSaleBadge(startsAt, new Date(startsAt.getTime() + 1))).toBe("On sale now");
+  });
+
+  it("spells the exact time out in the notice", () => {
+    expect(onSaleNotice(startsAt)).toBe(
+      `Tickets for this tier go on sale ${formatOnSaleAt(startsAt)}.`,
+    );
+  });
+});
+
+describe("maxAddableTickets", () => {
+  const now = new Date("2026-08-05T12:00:00.000Z");
+
+  it("is bounded by the seats the server would actually sell", () => {
+    expect(maxAddableTickets(tier({ quantity: 10, sold: 5, held: 3, maxPerPerson: 10 }), now)).toBe(2);
+  });
+
+  it("is bounded by maxPerPerson when that bites first", () => {
+    expect(maxAddableTickets(tier({ quantity: 100, sold: 0, held: 0, maxPerPerson: 4 }), now)).toBe(4);
+  });
+
+  it("is zero before a scheduled on-sale, even on a tier with the whole house free", () => {
+    // This is the (b) defect: 100 seats, nothing sold, and the server refuses
+    // every one of them with `ticket_not_yet_on_sale`.
+    const scheduled = tier({ quantity: 100, sold: 0, availableFrom: "2026-08-07T09:00:00.000Z" });
+    expect(maxAddableTickets(scheduled, now)).toBe(0);
+  });
+
+  it("opens to the normal cap the moment the on-sale time arrives", () => {
+    const at = "2026-08-05T12:00:00.000Z";
+    const t = tier({ quantity: 100, sold: 0, maxPerPerson: 4, availableFrom: at });
+    expect(maxAddableTickets(t, new Date(Date.parse(at) - 1))).toBe(0);
+    expect(maxAddableTickets(t, new Date(at))).toBe(4);
+  });
+
+  it("is zero for a tier whose remaining seats are all in other carts", () => {
+    expect(maxAddableTickets(tier({ quantity: 10, sold: 7, held: 3 }), now)).toBe(0);
+  });
+
+  it("never exceeds what the server will accept, for any tier shape", () => {
+    for (const quantity of [0, 1, 10]) {
+      for (const sold of [0, 1, 9]) {
+        for (const held of [0, 1, 5]) {
+          for (const maxPerPerson of [1, 4, 100]) {
+            const t = tier({ quantity, sold, held, maxPerPerson });
+            const cap = maxAddableTickets(t, now);
+            if (cap > 0) expect(serverWouldSell(t, cap)).toBe(true);
+          }
+        }
+      }
+    }
+  });
+});
+
+/**
+ * Events 2.6b — the offeree's OWN reservation.
+ *
+ * A waitlist offer takes a real hold, which is what stops a stranger taking the
+ * seat. The side effect is that the tier reads sold out to the person it is held
+ * for, so the picker has to know which of `held` is theirs — otherwise the claim
+ * link opens a page with the `+` disabled on the seat they were promised.
+ */
+describe("reservedForYou", () => {
+  const tier = { quantity: 10, sold: 8, held: 2, maxPerPerson: null, availableFrom: null };
+
+  it("changes nothing at all when omitted — every existing caller is untouched", () => {
+    expect(ticketSeatsAvailable(tier)).toBe(0);
+    expect(ticketSeatState(tier)).toBe("reserved_elsewhere");
+    expect(maxAddableTickets(tier)).toBe(0);
+  });
+
+  it("re-opens exactly the seats held for this visitor, and no more", () => {
+    expect(ticketSeatsAvailable(tier, 2)).toBe(2);
+    expect(ticketSeatState(tier, 2)).toBe("available");
+    expect(maxAddableTickets(tier, new Date(), 2)).toBe(2);
+    // Somebody else's seat is still somebody else's.
+    expect(ticketSeatsAvailable(tier, 1)).toBe(1);
+  });
+
+  it("never lets a claimed reservation exceed the artist's per-person cap", () => {
+    // The offer says how many seats are held; `maxPerPerson` says how many one
+    // person may hold at all, and an offer is not a licence to exceed it. The
+    // server applies the same cap, so exempting it here would only move the
+    // refusal to the card screen.
+    expect(maxAddableTickets({ ...tier, maxPerPerson: 1 }, new Date(), 2)).toBe(1);
+  });
+
+  it("cannot conjure seats out of a genuinely sold-out tier", () => {
+    const soldOut = { quantity: 5, sold: 5, held: 0, maxPerPerson: null, availableFrom: null };
+    // Nothing is held here, so nothing can be held FOR anybody. A tampered value
+    // buys nothing: the server re-derives the number from the hold it issued.
+    expect(ticketSeatsAvailable(soldOut, 3)).toBe(3);
+    // …which is why the guard that matters is the claim itself, not this
+    // arithmetic. What this pins is that a NEGATIVE or absent value is inert.
+    expect(ticketSeatsAvailable(soldOut, -3)).toBe(0);
+    expect(maxAddableTickets(soldOut, new Date(), -3)).toBe(0);
+  });
+
+  it("still refuses a tier whose on-sale time has not arrived", () => {
+    const scheduled = { ...tier, availableFrom: new Date(Date.now() + 86_400_000).toISOString() };
+    expect(maxAddableTickets(scheduled, new Date(), 2)).toBe(0);
+  });
+});

package/src/ui/format/attendees.ts

@@ -0,0 +1,187 @@
+import type { IEvent, ITicket } from "../../types/models";
+
+/**
+ * Events 2.1 — asking the buyer WHO IS COMING, on both rendering stacks.
+ *
+ * The operator toggle ("Ask for each attendee's name at checkout") and the
+ * server that accepts the answer both shipped; nothing ever asked. Every pass
+ * of a four-ticket order was therefore issued in the purchaser's name, and the
+ * setting looked broken because it was silent.
+ *
+ * ## Why the logic is here and not in a component
+ *
+ * There are two storefronts — `apps/client` (the PWA) and `packages/forge`'s
+ * own `<EventTickets>` (code sites) — and each renders its own checkout. The
+ * one thing they must NOT each derive for themselves is the shape of the
+ * request: `attendees` is keyed by ticket id and positional WITHIN a tier, and
+ * a list whose length does not equal that tier's quantity is refused outright
+ * by `validateAttendeeList` on the server. So slot construction, the buyer
+ * default, validation and the payload all live in these pure functions, and
+ * both stacks only decide what the inputs look like.
+ *
+ * ## Names only — deliberately
+ *
+ * The endpoint also accepts a per-attendee `email`, and that field is not a
+ * contact detail: `owner_email` is WHO HOLDS the pass, so naming a different
+ * address hands that seat to that person, who may then rename or transfer it
+ * instead of the buyer (`db/types/attendee.ts`, `commands/passTransfer.ts`).
+ * The operator toggle asks for a name and says so. Sending only names keeps
+ * every pass in the buyer's account — which is exactly the branch the backend
+ * documents as "what a storefront that only asks for names produces" — and
+ * leaves handing a ticket to somebody else to the transfer flow, which has a
+ * claim token, an expiry and an audit trail.
+ *
+ * ## A blank must never pass
+ *
+ * A missing name here is a person turned away at a door. The server's per-slot
+ * fallback would quietly put the BUYER's name on an unfilled seat rather than
+ * error, so a half-filled form would produce a wrong door list with a 200.
+ * `validateAttendeeNames` is what stops that before the request is made.
+ */
+
+/** Matches `validation.event.attendee_name.max` and the server's own cap. */
+export const MAX_ATTENDEE_NAME_LENGTH = 240;
+
+/**
+ * Trim and collapse internal whitespace — the same normalisation the server
+ * applies (`normalizeAttendeeName`), so "  Jane   Doe " and "Jane Doe" cannot
+ * sort into two places on a printed door list.
+ */
+export const normalizeAttendeeName = (raw?: string | null): string => (raw ?? "").replace(/\s+/g, " ").trim();
+
+/** Does this event ask for attendee names at all? Absent field means no. */
+export const collectsAttendees = (event?: Pick<IEvent, "collectAttendeeDetails"> | null): boolean =>
+  !!event?.collectAttendeeDetails;
+
+/** The buyer's own name, as the first seat's default. Empty until they type it. */
+export const buyerFullName = (input: { firstName?: string | null; lastName?: string | null }): string =>
+  normalizeAttendeeName(`${input.firstName ?? ""} ${input.lastName ?? ""}`);
+
+/** ticketId → the names typed so far, positional within that tier. */
+export type AttendeeNames = Record<string, (string | undefined)[]>;
+
+/** One seat the buyer has to name. */
+export type AttendeeSlot = {
+  ticketId: string;
+  ticketTitle: string;
+  /** 0-based position WITHIN this tier — the index the request is keyed on. */
+  index: number;
+  /** 1-based position within this tier, for a label. */
+  number: number;
+  /** How many seats of this tier are in the cart. */
+  ticketQuantity: number;
+  /**
+   * The very first seat in the cart. It defaults to the buyer, so the common
+   * case — one ticket, bought for yourself — asks for nothing already known.
+   */
+  isBuyer: boolean;
+  /** What the input should show: what they typed, else the buyer default. */
+  value: string;
+  /** "General Admission · Attendee 2 of 3", or just the tier on a single seat. */
+  label: string;
+};
+
+/**
+ * Every seat in the cart, in tier order then issue order.
+ *
+ * Derived from the CURRENT quantities on every call rather than stored, so a
+ * buyer who drops from four tickets to two cannot leave two orphan names behind
+ * (which the server would reject as a count mismatch) and one who goes back up
+ * to four gets what they already typed back.
+ *
+ * `undefined` and `""` are different on purpose: an untouched first seat shows
+ * the buyer's name, a first seat the buyer CLEARED stays empty and fails
+ * validation. Snapping it back would silently overrule a deliberate edit.
+ */
+export function buildAttendeeSlots(input: {
+  tickets: Pick<ITicket, "id" | "title">[];
+  quantities: Record<string, number>;
+  names: AttendeeNames;
+  /** Pre-fills the first seat only. Pass "" when the buyer has not typed a name yet. */
+  buyerName: string;
+}): AttendeeSlot[] {
+  const slots: AttendeeSlot[] = [];
+
+  for (const ticket of input.tickets) {
+    const quantity = Math.max(0, Math.floor(input.quantities[ticket.id] ?? 0));
+    for (let index = 0; index < quantity; index += 1) {
+      const isBuyer = slots.length === 0;
+      const typed = input.names[ticket.id]?.[index];
+      slots.push({
+        ticketId: ticket.id,
+        ticketTitle: ticket.title,
+        index,
+        number: index + 1,
+        ticketQuantity: quantity,
+        isBuyer,
+        value: typed !== undefined ? typed : isBuyer ? input.buyerName : "",
+        label: quantity > 1 ? `${ticket.title} · Attendee ${index + 1} of ${quantity}` : ticket.title,
+      });
+    }
+  }
+
+  return slots;
+}
+
+/** Write one seat's name back into the positional map. */
+export function setAttendeeName(names: AttendeeNames, ticketId: string, index: number, value: string): AttendeeNames {
+  const existing = names[ticketId] ?? [];
+  const next = existing.slice();
+  // A sparse array would serialise its holes as `null`; fill so every earlier
+  // seat stays `undefined` (= "not touched") rather than becoming a value.
+  while (next.length < index) next.push(undefined);
+  next[index] = value;
+  return { ...names, [ticketId]: next };
+}
+
+export type AttendeeProblem = "name_required" | "name_too_long";
+
+export type AttendeeCheck = { ok: true } | { ok: false; reason: AttendeeProblem; slot: AttendeeSlot; message: string };
+
+/**
+ * Every seat named, and no name over the cap.
+ *
+ * Returns the OFFENDING SLOT, not just a boolean, so a storefront can point at
+ * the field rather than say "something is missing" above a list of eight
+ * inputs.
+ */
+export function validateAttendeeNames(slots: AttendeeSlot[]): AttendeeCheck {
+  for (const slot of slots) {
+    const name = normalizeAttendeeName(slot.value);
+    if (name.length === 0) {
+      return {
+        ok: false,
+        reason: "name_required",
+        slot,
+        message: `Please enter a name for ${slot.label}.`,
+      };
+    }
+    if (name.length > MAX_ATTENDEE_NAME_LENGTH) {
+      return {
+        ok: false,
+        reason: "name_too_long",
+        slot,
+        message: `The name for ${slot.label} is too long (max ${MAX_ATTENDEE_NAME_LENGTH} characters).`,
+      };
+    }
+  }
+  return { ok: true };
+}
+
+/**
+ * The `attendees` map for `POST /public/events/:id/orders`.
+ *
+ * Built from the SLOTS, which is what guarantees exactly `quantity` entries per
+ * tier — the one shape the server refuses. Returns `undefined` when there is
+ * nothing to send, so an event that does not collect posts the body it always
+ * did (and the server does not read the field on that branch anyway).
+ */
+export function attendeesPayload(slots: AttendeeSlot[]): Record<string, { name: string }[]> | undefined {
+  if (slots.length === 0) return undefined;
+  const out: Record<string, { name: string }[]> = {};
+  for (const slot of slots) {
+    const list = (out[slot.ticketId] ??= []);
+    list[slot.index] = { name: normalizeAttendeeName(slot.value) };
+  }
+  return out;
+}

package/src/ui/format/membershipGate.ts

@@ -0,0 +1,209 @@
+import { safeRedirectPath } from "../../utils/safeRedirect";
+import type { MembershipGateReason, PublicMembershipGate } from "../../types/models";
+
+/**
+ * Members-only things, as a buyer has to see them (S.4, (c)).
+ *
+ * ## The defect this module exists to close
+ *
+ * The gate shipped ENFORCED and UNANNOUNCED. A logged-out buyer saw an ordinary
+ * ticket, chose a seat, typed their name and their email twice, and was refused
+ * on the last screen with a `MEMBERSHIP_GATE` 400 — the restriction was
+ * discoverable only by failing it. And the "members save X, sign in" funnel the
+ * feature was justified by existed on no surface at all, because nothing drew a
+ * way OUT of the refusal.
+ *
+ * ## Why it is pure, and why it lives in `format/`
+ *
+ * There are two rendering stacks — `apps/client` and the Forge SDK that code
+ * websites build against — and a members-only badge that says one thing on an
+ * artist's PWA and another on their website is the same bug twice. So the words
+ * and the resolving ACTION are decided once, here, with no React and no client;
+ * each stack owns only how it looks. `apps/client` imports this from
+ * `@tribe-nest/forge/ui`, exactly as it already does for the PWYW arithmetic.
+ *
+ * Pure and total also means the whole mapping is testable without a DOM or a
+ * session — and getting the two reasons backwards is the failure mode that
+ * matters most: telling someone who is already signed in to "sign in" is a loop
+ * with no exit, and telling a logged-out visitor to "upgrade" asks them to buy a
+ * membership they may already hold.
+ */
+
+// The wire shapes live in `types/models` beside the payloads that carry them;
+// re-exported here so a site importing the renderer gets the type with it.
+export type { MembershipGateReason, PublicMembershipGate };
+
+/** The API's stable machine-readable refusal code. Switch on this, never on prose. */
+export const MEMBERSHIP_GATE_CODE = "MEMBERSHIP_GATE";
+
+/** A `MEMBERSHIP_GATE` response, unpacked. */
+export type MembershipGateRefusal = {
+  reason: MembershipGateReason;
+  requiredTierIds: string[];
+  /** `event`, `event_ticket`, `course`, `product`, `post`. */
+  targetType: string;
+  targetId: string;
+  /** The API's own sentence, when it sent one. */
+  message: string | null;
+};
+
+type ApiErrorShape = {
+  response?: {
+    data?: {
+      code?: string;
+      message?: string;
+      details?: {
+        reason?: string;
+        requiredTierIds?: unknown;
+        targetType?: unknown;
+        targetId?: unknown;
+      };
+    };
+  };
+};
+
+const asStringArray = (value: unknown): string[] =>
+  Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+
+/**
+ * A thrown request → the gate refusal inside it, or `null` for anything else.
+ *
+ * Matched on `code`, not on the status: a checkout refusal is 400 and a read
+ * refusal is 401 or 403, and a client that switched on the status would render
+ * the members-only prompt as a session timeout on one of them.
+ *
+ * The `reason` is validated rather than cast. An unrecognised value falls back
+ * to `membership_required`, which is the safe half: it offers a way to BUY
+ * access, whereas a wrong `sign_in_required` offers a signed-in member a sign-in
+ * button that changes nothing.
+ */
+export function parseMembershipGateError(error: unknown): MembershipGateRefusal | null {
+  const data = (error as ApiErrorShape)?.response?.data;
+  if (!data || data.code !== MEMBERSHIP_GATE_CODE) return null;
+
+  const details = data.details ?? {};
+  return {
+    reason: details.reason === "sign_in_required" ? "sign_in_required" : "membership_required",
+    requiredTierIds: asStringArray(details.requiredTierIds),
+    targetType: typeof details.targetType === "string" ? details.targetType : "",
+    targetId: typeof details.targetId === "string" ? details.targetId : "",
+    message: typeof data.message === "string" && data.message.trim() ? data.message : null,
+  };
+}
+
+/**
+ * Is this thing refused to the caller looking at it?
+ *
+ * `null` means "nothing gates it" — which is also what every read returns while
+ * the `membership_entitlement_gates` switch is off. Treating an absent gate as
+ * "gated and permitted" would badge every item on every site the day the field
+ * shipped, so absent must read as false here and nowhere else.
+ */
+export function isMembershipGateLocked(gate: PublicMembershipGate | null | undefined): boolean {
+  return !!gate && !gate.allowed;
+}
+
+/** What a surface draws in place of, or beside, a gated thing. */
+export type MembershipGateNotice = {
+  reason: MembershipGateReason;
+  /** Two words for a list row, where a sentence does not fit. */
+  badge: string;
+  title: string;
+  body: string;
+  /** Primary CTA label — the way OUT of the refusal, which is the whole point. */
+  actionLabel: string;
+  /**
+   * Where the CTA goes. `null` only when the caller passed no path to send them
+   * to; a surface with a null href should render the notice without a button
+   * rather than a button that goes nowhere.
+   */
+  actionHref: string | null;
+};
+
+/** Default sign-in path. Overridden per site — code websites mount theirs under `/i`. */
+export const MEMBERSHIP_GATE_LOGIN_PATH = "/login";
+/** Default tier-listing path, i.e. where "become a member" actually leads. */
+export const MEMBERSHIP_GATE_MEMBERSHIP_PATH = "/membership";
+
+/** "Gold", "Gold or Platinum", "Gold, Silver or Bronze" — ANY one unlocks, hence "or". */
+export function joinTierNames(names: string[]): string {
+  const clean = names.map((name) => name.trim()).filter(Boolean);
+  if (clean.length === 0) return "";
+  if (clean.length === 1) return clean[0];
+  return `${clean.slice(0, -1).join(", ")} or ${clean[clean.length - 1]}`;
+}
+
+/** `path?redirect=<here>` — a sign-in that lands back on the thing they wanted. */
+export function membershipSignInHref(loginPath: string, currentPath: string): string {
+  const target = safeRedirectPath(currentPath, "");
+  return target ? `${loginPath}?redirect=${encodeURIComponent(target)}` : loginPath;
+}
+
+export interface BuildMembershipGateNoticeInput {
+  /** The announced gate from a listing/detail read. */
+  gate?: PublicMembershipGate | null;
+  /** A `MEMBERSHIP_GATE` refusal from a failed purchase. Wins over `gate` — it is the newer fact. */
+  refusal?: MembershipGateRefusal | null;
+  /**
+   * Names for `requiredTierIds`, already resolved by the caller (both stacks
+   * already fetch the public tier list). Ids are never shown: "you need tier
+   * 8f3c-…" is not a sentence anyone can act on.
+   */
+  tierNames?: string[];
+  /** What the thing IS, in the buyer's words — "This ticket", "This course". */
+  itemLabel?: string;
+  loginPath?: string;
+  membershipPath?: string;
+  /** Path (+ search) to return to after signing in. */
+  currentPath?: string;
+}
+
+/**
+ * The notice for a gated thing, or `null` when there is nothing to say.
+ *
+ * A `refusal` beats a `gate` because it is the more recent read of the same
+ * fact: the page may have rendered `allowed: true` from a stale cache, or the
+ * buyer's membership may have lapsed between the page load and the pay button,
+ * and the server's "no" at the moment of purchase is what actually happened.
+ */
+export function buildMembershipGateNotice(
+  input: BuildMembershipGateNoticeInput,
+): MembershipGateNotice | null {
+  const reason = input.refusal?.reason ?? (isMembershipGateLocked(input.gate) ? input.gate!.reason : null);
+  if (!reason) return null;
+
+  const item = input.itemLabel?.trim() || "This";
+  const tiers = joinTierNames(input.tierNames ?? []);
+  const loginPath = input.loginPath ?? MEMBERSHIP_GATE_LOGIN_PATH;
+  const membershipPath = input.membershipPath ?? MEMBERSHIP_GATE_MEMBERSHIP_PATH;
+
+  if (reason === "sign_in_required") {
+    return {
+      reason,
+      badge: "Members only",
+      title: "Members only",
+      // The API's own sentence is deliberately NOT used for this half. It is
+      // written for the refusal ("You must be a member to buy this"), and what
+      // an anonymous visitor needs first is the possibility that they already
+      // are one — which is the difference between a dead end and a funnel.
+      body: tiers
+        ? `${item} is for ${tiers} members. Already one? Sign in and it unlocks.`
+        : `${item} is for members. Already one? Sign in and it unlocks.`,
+      actionLabel: "Sign in",
+      actionHref: membershipSignInHref(loginPath, input.currentPath ?? ""),
+    };
+  }
+
+  return {
+    reason,
+    badge: "Members only",
+    title: "Members only",
+    body: tiers
+      ? `${item} is for ${tiers} members. Your current plan doesn't include it.`
+      : `${item} is for members. Your current plan doesn't include it.`,
+    // NOT "sign in" — they already are, and offering it again is a loop with no
+    // exit. The only move that changes anything is joining the tier.
+    actionLabel: tiers ? `View ${tiers}` : "View membership",
+    actionHref: membershipPath,
+  };
+}