@tribe-nest/forge 3.21.0 → 3.22.0

package/src/types/models.ts

@@ -80,6 +80,17 @@ export type PaymentStartResponse = {
   shippingCosts?: { deliveryGroupId: string; amount: number; currency: string }[];
   /** Authoritative sales-tax quote for this charge (all wired pillars). */
   taxQuote?: PublicTaxQuote;
+  /**
+   * When the reserved stock goes back on sale, ISO-8601 — the RESTARTED clock,
+   * measured from the card form rather than from when the cart was assembled,
+   * so this supersedes whatever the create call reported.
+   *
+   * `null` (or absent, on an older API) when this order holds no inventory:
+   * a digital/service-only cart, an already-settled free order, or a profile
+   * with the holds switch off. Nothing may show a countdown in that case —
+   * "no reservation" is not "expires now".
+   */
+  holdExpiresAt?: string | null;
 };
 
 /** Normalized result surfaced by usePaymentFlow. */
@@ -825,6 +836,11 @@ export type IPublicProduct = {
   height?: number;
   dimensionUnit?: string;
   shippingCountries?: string[] | null;
+  /**
+   * Members-only restriction, from `GET /public/products` and the detail read.
+   * `null`/absent when nothing gates it. See {@link PublicMembershipGate}.
+   */
+  membershipGate?: PublicMembershipGate | null;
 };
 
 export type QuestionnaireQuestion = {
@@ -885,6 +901,40 @@ export type CoachingProduct = {
   cancellation?: CancellationTermsView | null;
 };
 
+// ---- Membership gates (S.4) --------------------------------------------------
+
+/**
+ * `sign_in_required` — the server does not know who the caller is, so they may
+ * already be a member. `membership_required` — it does, and they are not.
+ *
+ * Same outcome, different next action. That is the entire reason the API
+ * distinguishes them instead of sending one "denied", and a renderer that
+ * collapses them either tells a signed-in member to sign in (a loop with no
+ * exit) or asks an anonymous visitor to buy a membership they may already hold.
+ */
+export type MembershipGateReason = "membership_required" | "sign_in_required";
+
+/**
+ * A members-only restriction, as announced by a PUBLIC read.
+ *
+ * Present on tickets, events, products and courses. `null` on anything ungated,
+ * and on everything in a workspace where the gates switch is off — so a surface
+ * that has never heard of this field behaves exactly as it did before.
+ *
+ * The item is ANNOUNCED, never hidden: "Gold members get first refusal on the
+ * vinyl" only works as an offer if non-members can see it. Which means the
+ * storefront owes the buyer the badge AND the way out of it — see
+ * `buildMembershipGateNotice` in `ui/format/membershipGate`.
+ */
+export type PublicMembershipGate = {
+  /** Which tiers unlock it. ANY one is enough — tiers are alternatives, never components. */
+  requiredTierIds: string[];
+  /** True when THIS caller may buy. */
+  allowed: boolean;
+  /** `null` exactly when `allowed`. */
+  reason: MembershipGateReason | null;
+};
+
 export type PublicCourseLesson = {
   id: string;
   title: string;
@@ -918,6 +968,15 @@ export type PublicCourse = {
   modules?: PublicCourseModule[];
   /** Rating aggregate — present on the detail endpoint, null until first published review. */
   reviewAggregate?: IReviewAggregate | null;
+  /**
+   * Members-only restriction — present on the course DETAIL read.
+   *
+   * A live gate locks the content even for someone holding a grant, because
+   * "this course is part of Gold" is a condition for access rather than a
+   * one-off unlock. So a lapsed member sees the outline and this gate, and the
+   * page owes them the way back in. See {@link PublicMembershipGate}.
+   */
+  membershipGate?: PublicMembershipGate | null;
 };
 
 // ---- Blog --------------------------------------------------------------------
@@ -1004,6 +1063,14 @@ export interface IEvent {
   timezone?: string;
   type: "physical" | "virtual" | "hybrid";
   ticketSaleMessage?: string;
+  /**
+   * Members-only restriction on the WHOLE event — no tier of it sells to a
+   * non-member. Distinct from `ITicket.membershipGate`, which restricts one tier
+   * alongside public ones, and the two are asserted separately at checkout: a
+   * page that collapses them badges every tier on a members-only event, or none
+   * on a members-only tier. Present on the detail read only.
+   */
+  membershipGate?: PublicMembershipGate | null;
   questionnaire?: {
     id: string;
     question: string;
@@ -1019,6 +1086,16 @@ export interface IEvent {
     country: string;
     zipCode?: string;
   };
+  /**
+   * The host asks for one NAME PER PASS at checkout (Events 2.1).
+   *
+   * Optional because every event that predates the feature comes down without
+   * it, and because a renderer must treat "absent" as "do not ask" — an event
+   * that has not opted in must be unaffected by the field existing at all. A
+   * checkout that ignores this ships four passes in the buyer's name and the
+   * artist's door list is wrong; see `ui/format/attendees.ts`.
+   */
+  collectAttendeeDetails?: boolean;
   title: string;
   description?: string;
   actionText: string;
@@ -1038,6 +1115,52 @@ export interface IEvent {
    * must not assume it is present.
    */
   bookingFee?: IBookingFee | null;
+  /**
+   * This event's `.ics` address, in both forms — the DETAIL endpoint only.
+   *
+   * `calendarUrl` is the https download; `calendarWebcalUrl` is the same
+   * address under the scheme iOS and macOS route to Calendar. Apple publishes
+   * no template URL the way Google and Microsoft do, so without these an
+   * add-to-calendar control has no Apple option at all — which is exactly the
+   * state every surface in this product was in until they existed.
+   *
+   * Not derivable client-side: the address carries a keyed HMAC. Optional
+   * because `useEvents()` (the list) deliberately does not mint one, and null
+   * for a cancelled show, where the feed would 404 anyway.
+   */
+  calendarUrl?: string | null;
+  calendarWebcalUrl?: string | null;
+  /**
+   * Whether this event has a presale behind a code, and whether the code sent
+   * with THIS request opened it (1.2).
+   *
+   * Present only on the DETAIL endpoint, and only there because it is the only
+   * page with a box to type a code into. Absent on `useEvents()`.
+   *
+   * Neither field is derivable from `tickets`: a hidden tier is filtered out
+   * server-side (so a presale-only event looks like an event with no tickets at
+   * all), and a VISIBLE code-gated tier is already listed (so the right code
+   * changes nothing on screen). A renderer that guessed would either show a code
+   * box on every event or call a correct code wrong.
+   */
+  presale?: IEventPresaleState;
+}
+
+/**
+ * The two facts a storefront needs to offer a presale-code box.
+ *
+ * It carries nothing about the codes themselves — not how many exist, not which
+ * tier a code opened. A visitor guessing learns only "not a code for this
+ * event", which is what they would learn by trying to check out anyway.
+ */
+export interface IEventPresaleState {
+  /** At least one live tier is code-gated. FALSE means: render no box at all. */
+  hasCodedTiers: boolean;
+  /**
+   * `null` when no code was sent — a first page load must not open with a
+   * rejection. `false` is the only value that should show "not valid".
+   */
+  codeAccepted: boolean | null;
 }
 
 // ---- Event series ------------------------------------------------------------
@@ -1128,6 +1251,27 @@ export type ITicket = {
   maxPerPerson: number;
   expiresAt?: string;
   archivedAt?: string;
+  /**
+   * This tier is not listed publicly (1.2). If you are looking at one, it is
+   * because a presale code revealed it — the server filters hidden tiers out of
+   * every response that did not carry the right code.
+   *
+   * Worth badging: a buyer who has just unlocked something should be able to
+   * SEE what unlocked, otherwise a correct code looks like it did nothing.
+   */
+  isHidden?: boolean;
+  /**
+   * Members-only restriction on THIS tier — the members-only ticket alongside
+   * public ones. Present on the event DETAIL read; absent on list endpoints,
+   * which quote no ticket and offer no buy button.
+   *
+   * A gated tier stays in the list on purpose: hiding it kills the upsell that
+   * is the whole reason to sell a members-only ticket. So a renderer must badge
+   * it and offer the resolving action — sign in, or view the tier — rather than
+   * let the buyer discover the gate by being refused at payment. See
+   * {@link PublicMembershipGate}.
+   */
+  membershipGate?: PublicMembershipGate | null;
 };
 
 // ---- Invoices ----------------------------------------------------------------
@@ -1423,6 +1567,13 @@ export type CoachingBooking = {
   productTitle?: string | null;
   durationMinutes?: number | null;
   timezone?: string | null;
+  /**
+   * The session's `.ics`, both forms — see {@link CalendarFeedLinks}. Null
+   * unless the booking is CONFIRMED: a held slot is not a session, and offering
+   * to diarise a cancelled one is worse than offering nothing.
+   */
+  calendarUrl?: string | null;
+  calendarWebcalUrl?: string | null;
 };
 
 export type CourseBooking = {

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

@@ -0,0 +1,231 @@
+import { describe, it, expect } from "vitest";
+import type { ITicket } from "../../../types/models";
+import {
+  attendeesPayload,
+  buildAttendeeSlots,
+  buyerFullName,
+  collectsAttendees,
+  MAX_ATTENDEE_NAME_LENGTH,
+  normalizeAttendeeName,
+  setAttendeeName,
+  validateAttendeeNames,
+  type AttendeeNames,
+} from "../attendees";
+
+/**
+ * Per-attendee names at checkout, shared by BOTH storefront stacks.
+ *
+ * Two properties matter more than the rest and are pinned first:
+ *
+ *  1. An event that does not ask produces NO slots, NO validation and NO
+ *     payload — every pre-2.1 event must post the body it always posted.
+ *  2. The payload always carries exactly `quantity` entries per tier. The
+ *     server refuses any other length (`validateAttendeeList` →
+ *     `count_mismatch`), and a short list that slipped past would leave a
+ *     silent pass in the purchaser's name — a stranger at the door.
+ */
+
+const tier = (over: Partial<ITicket> = {}): ITicket => ({
+  id: over.id ?? "t1",
+  title: over.title ?? "GA",
+  description: "",
+  price: 20,
+  quantity: 100,
+  order: 0,
+  sold: 0,
+  maxPerPerson: 10,
+  ...over,
+});
+
+const ga = tier({ id: "ga", title: "General Admission" });
+const vip = tier({ id: "vip", title: "VIP" });
+
+const slots = (input: {
+  quantities: Record<string, number>;
+  names?: AttendeeNames;
+  buyerName?: string;
+  tickets?: ITicket[];
+}) =>
+  buildAttendeeSlots({
+    tickets: input.tickets ?? [ga, vip],
+    quantities: input.quantities,
+    names: input.names ?? {},
+    buyerName: input.buyerName ?? "",
+  });
+
+describe("attendee helpers", () => {
+  describe("collectsAttendees", () => {
+    it("is false when the field is absent — every event that predates the feature", () => {
+      expect(collectsAttendees({} as never)).toBe(false);
+      expect(collectsAttendees(null)).toBe(false);
+      expect(collectsAttendees(undefined)).toBe(false);
+    });
+
+    it("is true only when the host actually turned it on", () => {
+      expect(collectsAttendees({ collectAttendeeDetails: true })).toBe(true);
+      expect(collectsAttendees({ collectAttendeeDetails: false })).toBe(false);
+    });
+  });
+
+  describe("normalizeAttendeeName", () => {
+    it("collapses whitespace so one person cannot sort into two door-list rows", () => {
+      expect(normalizeAttendeeName("  Jane   Doe ")).toBe("Jane Doe");
+    });
+
+    it("treats an all-whitespace name as empty", () => {
+      expect(normalizeAttendeeName("   ")).toBe("");
+      expect(normalizeAttendeeName(undefined)).toBe("");
+    });
+  });
+
+  describe("buyerFullName", () => {
+    it("joins the two halves the checkout already collected", () => {
+      expect(buyerFullName({ firstName: "Jane", lastName: "Doe" })).toBe("Jane Doe");
+    });
+
+    it("is empty before the buyer has typed anything — not a stray space", () => {
+      expect(buyerFullName({ firstName: "", lastName: "" })).toBe("");
+      expect(buyerFullName({})).toBe("");
+    });
+  });
+
+  describe("buildAttendeeSlots", () => {
+    it("makes one slot per seat, in tier then issue order", () => {
+      const built = slots({ quantities: { ga: 2, vip: 1 } });
+      expect(built.map((s) => [s.ticketId, s.index])).toEqual([
+        ["ga", 0],
+        ["ga", 1],
+        ["vip", 0],
+      ]);
+    });
+
+    it("skips a tier with no seats selected", () => {
+      expect(slots({ quantities: { vip: 1 } }).map((s) => s.ticketId)).toEqual(["vip"]);
+    });
+
+    it("pre-fills ONLY the first seat with the buyer, so nothing known is retyped", () => {
+      const built = slots({ quantities: { ga: 2 }, buyerName: "Jane Doe" });
+      expect(built[0]).toMatchObject({ isBuyer: true, value: "Jane Doe" });
+      expect(built[1]).toMatchObject({ isBuyer: false, value: "" });
+    });
+
+    it("keeps a first seat the buyer deliberately CLEARED empty", () => {
+      // "" is a decision; `undefined` is "untouched". Snapping a cleared field
+      // back to the buyer's name would overrule the person filling the form.
+      const built = slots({ quantities: { ga: 1 }, names: { ga: [""] }, buyerName: "Jane Doe" });
+      expect(built[0].value).toBe("");
+    });
+
+    it("labels each seat with its tier, and numbers them only when there is more than one", () => {
+      expect(slots({ quantities: { vip: 1 } })[0].label).toBe("VIP");
+      expect(slots({ quantities: { ga: 3 } }).map((s) => s.label)).toEqual([
+        "General Admission — Attendee 1 of 3",
+        "General Admission — Attendee 2 of 3",
+        "General Admission — Attendee 3 of 3",
+      ]);
+    });
+
+    it("drops names past the current quantity — no orphan when the buyer reduces the cart", () => {
+      const names: AttendeeNames = { ga: ["A", "B", "C", "D"] };
+      const built = slots({ quantities: { ga: 2 }, names });
+      expect(built.map((s) => s.value)).toEqual(["A", "B"]);
+      // And going back up restores what was already typed rather than blanking it.
+      expect(slots({ quantities: { ga: 4 }, names }).map((s) => s.value)).toEqual(["A", "B", "C", "D"]);
+    });
+
+    it("ignores a negative or fractional quantity rather than producing junk seats", () => {
+      expect(slots({ quantities: { ga: -3 } })).toHaveLength(0);
+      expect(slots({ quantities: { ga: 2.7 } })).toHaveLength(2);
+    });
+  });
+
+  describe("setAttendeeName", () => {
+    it("writes one seat without disturbing the others", () => {
+      const next = setAttendeeName({ ga: ["A", "B"] }, "ga", 1, "Bee");
+      expect(next.ga).toEqual(["A", "Bee"]);
+    });
+
+    it("leaves earlier untouched seats as `undefined`, not as holes or empty strings", () => {
+      const next = setAttendeeName({}, "ga", 2, "C");
+      expect(next.ga).toEqual([undefined, undefined, "C"]);
+      // A hole would serialise to `null`; these must stay "not typed yet" so the
+      // first seat can still show the buyer default.
+      expect(0 in (next.ga as unknown[])).toBe(true);
+    });
+
+    it("does not mutate the previous state", () => {
+      const prev: AttendeeNames = { ga: ["A"] };
+      setAttendeeName(prev, "ga", 0, "Z");
+      expect(prev.ga).toEqual(["A"]);
+    });
+  });
+
+  describe("validateAttendeeNames", () => {
+    it("passes an empty list — an event that does not ask has nothing to validate", () => {
+      expect(validateAttendeeNames([])).toEqual({ ok: true });
+    });
+
+    it("refuses a blank seat and names WHICH one", () => {
+      const built = slots({ quantities: { ga: 2 }, names: { ga: ["Jane"] } });
+      const result = validateAttendeeNames(built);
+      expect(result.ok).toBe(false);
+      if (result.ok) return;
+      expect(result.reason).toBe("name_required");
+      expect(result.slot.index).toBe(1);
+      expect(result.message).toContain("General Admission — Attendee 2 of 2");
+    });
+
+    it("refuses whitespace-only, which would otherwise write an empty owner_name", () => {
+      const built = slots({ quantities: { ga: 1 }, names: { ga: ["   "] } });
+      expect(validateAttendeeNames(built).ok).toBe(false);
+    });
+
+    it("refuses a name over the server's cap rather than letting the request 400", () => {
+      const built = slots({ quantities: { ga: 1 }, names: { ga: ["x".repeat(MAX_ATTENDEE_NAME_LENGTH + 1)] } });
+      const result = validateAttendeeNames(built);
+      expect(result.ok).toBe(false);
+      if (result.ok) return;
+      expect(result.reason).toBe("name_too_long");
+    });
+
+    it("accepts a name exactly at the cap", () => {
+      const built = slots({ quantities: { ga: 1 }, names: { ga: ["x".repeat(MAX_ATTENDEE_NAME_LENGTH)] } });
+      expect(validateAttendeeNames(built)).toEqual({ ok: true });
+    });
+
+    it("accepts the buyer default on an untouched first seat — that IS an answer", () => {
+      const built = slots({ quantities: { ga: 1 }, buyerName: "Jane Doe" });
+      expect(validateAttendeeNames(built)).toEqual({ ok: true });
+    });
+  });
+
+  describe("attendeesPayload", () => {
+    it("is undefined with no slots, so the field is omitted from the body entirely", () => {
+      expect(attendeesPayload([])).toBeUndefined();
+    });
+
+    it("keys by ticket id with exactly `quantity` entries per tier, in issue order", () => {
+      const built = slots({ quantities: { ga: 2, vip: 1 }, names: { ga: ["Jane", "John"], vip: ["Ada"] } });
+      expect(attendeesPayload(built)).toEqual({
+        ga: [{ name: "Jane" }, { name: "John" }],
+        vip: [{ name: "Ada" }],
+      });
+    });
+
+    it("sends the buyer's own name for the untouched first seat", () => {
+      const built = slots({ quantities: { ga: 2 }, names: { ga: [undefined, "John"] }, buyerName: "Jane Doe" });
+      expect(attendeesPayload(built)).toEqual({ ga: [{ name: "Jane Doe" }, { name: "John" }] });
+    });
+
+    it("normalises before sending, so the door list matches what the server stores", () => {
+      const built = slots({ quantities: { ga: 1 }, names: { ga: ["  Jane   Doe "] } });
+      expect(attendeesPayload(built)).toEqual({ ga: [{ name: "Jane Doe" }] });
+    });
+
+    it("never sends an email — a per-attendee address would hand the pass away", () => {
+      const built = slots({ quantities: { ga: 1 }, names: { ga: ["Jane"] } });
+      const payload = attendeesPayload(built)!;
+      expect(Object.keys(payload.ga[0])).toEqual(["name"]);
+    });
+  });
+});

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

@@ -0,0 +1,220 @@
+import { describe, it, expect } from "vitest";
+import {
+  buildMembershipGateNotice,
+  isMembershipGateLocked,
+  joinTierNames,
+  membershipSignInHref,
+  parseMembershipGateError,
+  type PublicMembershipGate,
+} from "../membershipGate";
+
+/**
+ * The members-only rendering rule, shared by BOTH storefront stacks.
+ *
+ * These tests exist because the two halves of the gate are trivially easy to
+ * swap and the swap is invisible: both produce a plausible-looking notice, and
+ * only a real buyer discovers that one of them is a dead end (a signed-in
+ * member told to sign in) and the other asks for money that has already been
+ * paid.
+ */
+
+const gate = (over: Partial<PublicMembershipGate> = {}): PublicMembershipGate => ({
+  requiredTierIds: ["gold"],
+  allowed: false,
+  reason: "membership_required",
+  ...over,
+});
+
+const apiError = (data: unknown) => ({ response: { data } });
+
+describe("isMembershipGateLocked", () => {
+  it("an ABSENT gate is not a lock", () => {
+    // Every read returns null while the switch is off. Treating absent as
+    // "gated" would badge every item on every site the day the field shipped.
+    expect(isMembershipGateLocked(null)).toBe(false);
+    expect(isMembershipGateLocked(undefined)).toBe(false);
+  });
+
+  it("an allowed gate is not a lock, a refused one is", () => {
+    expect(isMembershipGateLocked(gate({ allowed: true, reason: null, requiredTierIds: [] }))).toBe(false);
+    expect(isMembershipGateLocked(gate())).toBe(true);
+  });
+});
+
+describe("parseMembershipGateError", () => {
+  it("ignores anything that is not a MEMBERSHIP_GATE", () => {
+    expect(parseMembershipGateError(new Error("boom"))).toBeNull();
+    expect(parseMembershipGateError(apiError({ code: "INVENTORY_HOLD_EXPIRED" }))).toBeNull();
+    expect(parseMembershipGateError(apiError({ message: "Sold out" }))).toBeNull();
+    expect(parseMembershipGateError(undefined)).toBeNull();
+  });
+
+  it("unpacks details and keeps the API's own sentence", () => {
+    expect(
+      parseMembershipGateError(
+        apiError({
+          code: "MEMBERSHIP_GATE",
+          message: "Members only: “Front row” is for members.",
+          details: {
+            reason: "membership_required",
+            requiredTierIds: ["gold", "platinum"],
+            targetType: "event_ticket",
+            targetId: "tick-1",
+          },
+        }),
+      ),
+    ).toEqual({
+      reason: "membership_required",
+      requiredTierIds: ["gold", "platinum"],
+      targetType: "event_ticket",
+      targetId: "tick-1",
+      message: "Members only: “Front row” is for members.",
+    });
+  });
+
+  it("matches on CODE, not on status — a read refusal is 401/403, a checkout refusal 400", () => {
+    // Nothing here reads a status at all; the same payload parses whichever
+    // status carried it. A client switching on 401 would render this as a
+    // session timeout.
+    const parsed = parseMembershipGateError(
+      apiError({ code: "MEMBERSHIP_GATE", details: { reason: "sign_in_required" } }),
+    );
+    expect(parsed?.reason).toBe("sign_in_required");
+  });
+
+  it("falls back to membership_required on an unknown reason", () => {
+    // The safe half: it offers a way to BUY access. A wrong `sign_in_required`
+    // offers a signed-in member a button that changes nothing.
+    expect(parseMembershipGateError(apiError({ code: "MEMBERSHIP_GATE", details: { reason: "wat" } }))?.reason).toBe(
+      "membership_required",
+    );
+    expect(parseMembershipGateError(apiError({ code: "MEMBERSHIP_GATE" }))?.reason).toBe("membership_required");
+  });
+
+  it("survives a malformed details block without throwing", () => {
+    expect(
+      parseMembershipGateError(
+        apiError({ code: "MEMBERSHIP_GATE", details: { requiredTierIds: "gold", targetId: 7 } }),
+      ),
+    ).toEqual({
+      reason: "membership_required",
+      requiredTierIds: [],
+      targetType: "",
+      targetId: "",
+      message: null,
+    });
+  });
+});
+
+describe("joinTierNames", () => {
+  it("joins with OR, because any one tier is enough", () => {
+    expect(joinTierNames(["Gold"])).toBe("Gold");
+    expect(joinTierNames(["Gold", "Platinum"])).toBe("Gold or Platinum");
+    expect(joinTierNames(["Gold", "Silver", "Bronze"])).toBe("Gold, Silver or Bronze");
+  });
+
+  it("drops blanks — an unresolved tier must not become an empty slot", () => {
+    expect(joinTierNames(["", "  ", "Gold"])).toBe("Gold");
+    expect(joinTierNames([])).toBe("");
+  });
+});
+
+describe("membershipSignInHref", () => {
+  it("returns the buyer to what they were trying to buy", () => {
+    expect(membershipSignInHref("/i/login", "/i/events/spring-tour")).toBe(
+      "/i/login?redirect=%2Fi%2Fevents%2Fspring-tour",
+    );
+  });
+
+  it("refuses an off-site redirect target", () => {
+    expect(membershipSignInHref("/login", "https://evil.example")).toBe("/login");
+    expect(membershipSignInHref("/login", "//evil.example")).toBe("/login");
+    expect(membershipSignInHref("/login", "")).toBe("/login");
+  });
+});
+
+describe("buildMembershipGateNotice", () => {
+  it("says nothing when nothing is gated", () => {
+    expect(buildMembershipGateNotice({})).toBeNull();
+    expect(buildMembershipGateNotice({ gate: null })).toBeNull();
+    expect(buildMembershipGateNotice({ gate: gate({ allowed: true, reason: null }) })).toBeNull();
+  });
+
+  it("offers SIGN IN to a visitor we cannot identify, and returns them here", () => {
+    const notice = buildMembershipGateNotice({
+      gate: gate({ reason: "sign_in_required" }),
+      tierNames: ["Gold"],
+      itemLabel: "This ticket",
+      loginPath: "/i/login",
+      currentPath: "/i/events/spring-tour",
+    });
+
+    expect(notice).toMatchObject({
+      reason: "sign_in_required",
+      badge: "Members only",
+      actionLabel: "Sign in",
+      actionHref: "/i/login?redirect=%2Fi%2Fevents%2Fspring-tour",
+    });
+    // The possibility that they already ARE a member is the funnel; without it
+    // this is just a locked door.
+    expect(notice!.body).toBe("This ticket is for Gold members. Already one? Sign in and it unlocks.");
+  });
+
+  it("offers the TIER to someone already signed in — never sign-in again", () => {
+    const notice = buildMembershipGateNotice({
+      gate: gate({ reason: "membership_required", requiredTierIds: ["gold", "plat"] }),
+      tierNames: ["Gold", "Platinum"],
+      itemLabel: "This course",
+      membershipPath: "/i/membership",
+    });
+
+    expect(notice).toMatchObject({
+      reason: "membership_required",
+      actionLabel: "View Gold or Platinum",
+      actionHref: "/i/membership",
+    });
+    expect(notice!.body).toBe("This course is for Gold or Platinum members. Your current plan doesn't include it.");
+    // Telling a signed-in member to sign in is a loop with no exit.
+    expect(notice!.actionLabel).not.toMatch(/sign in/i);
+  });
+
+  it("still reads as a sentence when the tier names have not resolved", () => {
+    // The tier list is a second request; it can be in flight, or the gating tier
+    // can be one the public list does not carry. An id is not a sentence.
+    const notice = buildMembershipGateNotice({ gate: gate(), itemLabel: "This ticket" });
+    expect(notice!.body).toBe("This ticket is for members. Your current plan doesn't include it.");
+    expect(notice!.actionLabel).toBe("View membership");
+    expect(notice!.body).not.toContain("gold");
+  });
+
+  it("falls back to a generic subject with no item label", () => {
+    expect(buildMembershipGateNotice({ gate: gate() })!.body).toBe(
+      "This is for members. Your current plan doesn't include it.",
+    );
+  });
+
+  it("a REFUSAL overrides a stale announced gate", () => {
+    // The page rendered `allowed: true` from cache, or the membership lapsed
+    // between page load and pay. The server's no at the moment of purchase is
+    // what actually happened.
+    const notice = buildMembershipGateNotice({
+      gate: gate({ allowed: true, reason: null, requiredTierIds: [] }),
+      refusal: {
+        reason: "membership_required",
+        requiredTierIds: ["gold"],
+        targetType: "event_ticket",
+        targetId: "tick-1",
+        message: "Members only.",
+      },
+      tierNames: ["Gold"],
+      itemLabel: "This ticket",
+    });
+
+    expect(notice).toMatchObject({ reason: "membership_required", actionLabel: "View Gold" });
+  });
+
+  it("uses default paths when the host names none", () => {
+    expect(buildMembershipGateNotice({ gate: gate() })!.actionHref).toBe("/membership");
+    expect(buildMembershipGateNotice({ gate: gate({ reason: "sign_in_required" }) })!.actionHref).toBe("/login");
+  });
+});