@tribe-nest/forge 3.20.0 → 3.22.0

package/src/server/index.ts

@@ -47,6 +47,14 @@ import type {
   CollectionSearchResult,
 } from "../types/models";
 import { collectionParamsToQuery, splitCollectionQuery } from "../data/collectionParams";
+// SEO context for structured data. Pure functions over plain data, so this is
+// safe in the React-free server entry.
+import {
+  seoContextFromSiteConfig,
+  type ReviewSchemaReview,
+  type SiteSeoContext,
+} from "../utils/structuredData";
+export type { SiteSeoContext };
 import type { SiteConfig } from "../data/queries/useWebsite";
 
 /**
@@ -121,6 +129,50 @@ export function fetchSiteConfig(opts: { apiUrl: string; profileId?: string }): P
   return getJson<SiteConfig>(opts.apiUrl, "/public/websites/site-config", { profileId: opts.profileId });
 }
 
+/**
+ * A sample of an entity's published reviews, for the `review` array in its
+ * JSON-LD. Sorted by "helpful" so the sample Google reads is the useful one.
+ *
+ * Purely an enrichment: the star snippet comes from `aggregateRating`, which
+ * every detail payload already carries. Only call this when the entity HAS
+ * reviews — the sample is worth one round trip for a reviewed thing and worth
+ * none for an unreviewed one.
+ */
+export async function fetchEntityReviewsServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+  entityType: "product" | "course" | "coaching_product";
+  entityId: string;
+  limit?: number;
+}): Promise<ReviewSchemaReview[]> {
+  if (!opts.profileId) return [];
+  const res = await getJson<{ data: ReviewSchemaReview[] }>(opts.apiUrl, "/public/reviews", {
+    profileId: opts.profileId,
+    entityType: opts.entityType,
+    entityId: opts.entityId,
+    page: "1",
+    limit: String(opts.limit ?? 5),
+    sort: "helpful",
+  });
+  return res?.data ?? [];
+}
+
+/**
+ * The tenant facts the JSON-LD builders need (settlement currency + creator
+ * name), for a detail route's OWN loader.
+ *
+ * Fetched per route rather than read off the root match on purpose: during SSR
+ * a child `head()` sees the root match with `loaderData: null`, so the root's
+ * site config is invisible there. Pair it with the entity fetch in one
+ * `Promise.all` and the extra round trip costs nothing wall-clock.
+ */
+export async function fetchSeoContextServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+}): Promise<SiteSeoContext> {
+  return seoContextFromSiteConfig(await fetchSiteConfig(opts));
+}
+
 /** The API's unauthenticated liveness route — no tenant, no params, no body. */
 const PROBE_PATH = "/healthcheck";
 

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