@tribe-nest/forge 3.20.0 → 3.22.0

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

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,
+  };
+}