@tribe-nest/forge 3.22.0 → 3.24.0

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

@@ -119,9 +119,9 @@ describe("attendee helpers", () => {
     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",
+        "General Admission · Attendee 1 of 3",
+        "General Admission · Attendee 2 of 3",
+        "General Admission · Attendee 3 of 3",
       ]);
     });
 
@@ -172,7 +172,7 @@ describe("attendee helpers", () => {
       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");
+      expect(result.message).toContain("General Admission · Attendee 2 of 2");
     });
 
     it("refuses whitespace-only, which would otherwise write an empty owner_name", () => {

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

@@ -77,7 +77,7 @@ export type AttendeeSlot = {
   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. */
+  /** "General Admission · Attendee 2 of 3", or just the tier on a single seat. */
   label: string;
 };
 
@@ -115,7 +115,7 @@ export function buildAttendeeSlots(input: {
         ticketQuantity: quantity,
         isBuyer,
         value: typed !== undefined ? typed : isBuyer ? input.buyerName : "",
-        label: quantity > 1 ? `${ticket.title} — Attendee ${index + 1} of ${quantity}` : ticket.title,
+        label: quantity > 1 ? `${ticket.title} · Attendee ${index + 1} of ${quantity}` : ticket.title,
       });
     }
   }

package/src/ui/format/ticketAvailability.ts

@@ -0,0 +1,226 @@
+import type { ITicket } from "../../types/models";
+
+/**
+ * When a ticket tier may be BOUGHT, as a storefront has to draw it.
+ *
+ * ## The two defects this module exists to close
+ *
+ * Both are the same shape: the buyer's screen and the server disagreed, and the
+ * buyer discovered it only by being refused after doing the work.
+ *
+ * **(a) Held seats were shown as available.** Every storefront computed
+ * remaining as `quantity - sold`. The server sells on `quantity - sold - held`
+ * (`services/_core/inventoryHold.ts` — `quantity - sold - held >= n`), where
+ * `held` is inventory promised to somebody else's in-flight checkout. During an
+ * on-sale rush a fan saw "3 left", picked 2, filled in their details, and was
+ * refused at reserve because those three seats were in other people's carts.
+ *
+ * **(b) A scheduled on-sale rendered as buyable.** `availableFrom` shipped on
+ * the tier, is enforced by `evaluateTierSellability`, is published in
+ * `PUBLIC_TICKET_COLUMNS` — and appeared on NEITHER rendering stack. A tier
+ * going on sale Friday 10am was fully clickable on Wednesday, and the refusal
+ * arrived as `ticket_not_yet_on_sale` on the payment screen.
+ *
+ * ## Why it is pure, and why it lives in `format/`
+ *
+ * There are two rendering stacks — `apps/client` and the Forge SDK that code
+ * websites are built against — and availability arithmetic that says one thing
+ * on an artist's PWA and another on their website is the same bug twice. So the
+ * arithmetic and the words 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
+ * and the members-only notice.
+ *
+ * ## The client is not the guard
+ *
+ * `createOrder` re-checks every one of these against the tier's own columns and
+ * refuses regardless of what a client sends. Nothing here makes a request safe.
+ * What it does is stop a buyer building a cart nobody will sell them.
+ */
+
+/**
+ * Seats a buyer can actually take right now — the SERVER's arithmetic.
+ *
+ * `held` counts units inside somebody else's live checkout. It is optional on
+ * the type and absent-means-zero on purpose: a site pinned to an older API
+ * build that does not publish the column keeps exactly its previous behaviour
+ * rather than reading every tier as sold out.
+ */
+export const ticketSeatsAvailable = (
+  ticket: Pick<ITicket, "quantity" | "sold" | "held">,
+  /**
+   * Seats inside `held` that are held for THIS visitor (events 2.6b).
+   *
+   * A waitlist offer now takes a real inventory hold for the length of its
+   * claim window, which is the whole point — a stranger cannot take the seat
+   * the email promised. The consequence is that the tier reads sold out to
+   * everybody, INCLUDING the person it is being held for: their own reservation
+   * is in `held`, so the picker would refuse to let them add the seat they were
+   * offered, and the claim link would be unusable.
+   *
+   * Adding their own reservation back is not a loophole. It is spendable only
+   * by presenting the claim token, the server re-derives the same number from
+   * the hold it issued, and a visitor who invents a value simply gets refused
+   * at `createOrder` exactly as before.
+   *
+   * Zero by default, so every existing caller is byte-for-byte unchanged.
+   */
+  reservedForYou = 0,
+): number =>
+  Math.max(0, (ticket.quantity ?? 0) - (ticket.sold ?? 0) - (ticket.held ?? 0) + Math.max(0, reservedForYou));
+
+/**
+ * Seats that are not sold — held or otherwise.
+ *
+ * The difference between this and {@link ticketSeatsAvailable} is precisely the
+ * set of seats sitting in other people's checkouts, which is what separates
+ * "gone" from "gone for the next few minutes".
+ */
+export const ticketSeatsUnsold = (ticket: Pick<ITicket, "quantity" | "sold">): number =>
+  Math.max(0, (ticket.quantity ?? 0) - (ticket.sold ?? 0));
+
+/**
+ * Why a buyer cannot take a seat, when they cannot.
+ *
+ * `reserved_elsewhere` is deliberately NOT collapsed into `sold_out`. They are
+ * different facts with different right actions: a sold-out tier is over and the
+ * fan should join the waitlist or leave; a tier whose last seats are inside
+ * somebody's checkout may well be buyable in ten minutes, and telling that fan
+ * "SOLD OUT" loses a sale that was still there. It is also the state a rush
+ * produces most often, which is exactly when the wrong word costs the most.
+ */
+export type TicketSeatState = "available" | "reserved_elsewhere" | "sold_out";
+
+export const ticketSeatState = (
+  ticket: Pick<ITicket, "quantity" | "sold" | "held">,
+  /** 2.6b — seats of `held` that are this visitor's own waitlist reservation. */
+  reservedForYou = 0,
+): TicketSeatState => {
+  if (ticketSeatsAvailable(ticket, reservedForYou) > 0) return "available";
+  return ticketSeatsUnsold(ticket) > 0 ? "reserved_elsewhere" : "sold_out";
+};
+
+/**
+ * The short word in the stepper, where "SOLD OUT" already lives.
+ *
+ * Kept to two words because it renders in a fixed-width slot between the − and
+ * + buttons; the sentence that explains it is {@link ticketSeatNotice}.
+ */
+export const ticketSeatLabel = (state: TicketSeatState): string | null => {
+  if (state === "sold_out") return "SOLD OUT";
+  if (state === "reserved_elsewhere") return "ON HOLD";
+  return null;
+};
+
+/** The sentence under a tier that cannot be added, or `null` when it can. */
+export const ticketSeatNotice = (state: TicketSeatState): string | null => {
+  if (state !== "reserved_elsewhere") return null;
+  return "The last seats are in someone else's checkout. They may be released in a few minutes, so check back.";
+};
+
+/**
+ * Has this tier's on-sale time arrived?
+ *
+ * Mirrors `evaluateTierSellability`'s `not_yet_on_sale` branch exactly, down to
+ * the strict comparison: the server refuses while `now < availableFrom`, so a
+ * storefront that allowed the boundary second would produce the one refusal
+ * this whole module exists to prevent.
+ */
+export type TicketSaleWindow = { status: "open" } | { status: "scheduled"; startsAt: Date };
+
+export const ticketSaleWindow = (
+  ticket: Pick<ITicket, "availableFrom">,
+  now: Date = new Date(),
+): TicketSaleWindow => {
+  if (!ticket.availableFrom) return { status: "open" };
+  const startsAt = new Date(ticket.availableFrom);
+  if (Number.isNaN(startsAt.getTime())) return { status: "open" };
+  return now < startsAt ? { status: "scheduled", startsAt } : { status: "open" };
+};
+
+/** `true` only while a scheduled tier's on-sale time is still in the future. */
+export const isTicketScheduled = (
+  ticket: Pick<ITicket, "availableFrom">,
+  now: Date = new Date(),
+): boolean => ticketSaleWindow(ticket, now).status === "scheduled";
+
+/**
+ * The buyer's local rendering of an on-sale instant.
+ *
+ * Buyer-local, not the event's timezone: this answers "when can I click buy?",
+ * which happens where the buyer is. The server compares absolute instants, so
+ * the two cannot disagree about WHEN — only about how it reads.
+ *
+ * Matches the format the waitlist claim deadline and the transfer panel already
+ * use, so three different "when" strings on one event page look like one voice.
+ */
+export const formatOnSaleAt = (startsAt: Date): string =>
+  startsAt.toLocaleString(undefined, {
+    weekday: "short",
+    day: "numeric",
+    month: "short",
+    hour: "numeric",
+    minute: "2-digit",
+  });
+
+/**
+ * The badge for a tier that is announced but not yet buyable.
+ *
+ * Under an hour it counts down, because at that range "10:00" is worth less to
+ * a waiting fan than "in 12 minutes" and the tier list already re-renders every
+ * second for the expiry urgency. Above it, the absolute time is what someone
+ * plans their Friday around.
+ *
+ * A tier that is merely not-yet-on-sale stays VISIBLE (see
+ * `isTierPubliclyVisible`) — that is the point. Hiding it would make a
+ * scheduled on-sale indistinguishable from the tier not existing.
+ */
+export const onSaleBadge = (startsAt: Date, now: Date = new Date()): string => {
+  const diffMs = startsAt.getTime() - now.getTime();
+  if (diffMs <= 0) return "On sale now";
+  const minutes = Math.ceil(diffMs / 60_000);
+  if (minutes < 60) return `On sale in ${minutes} minute${minutes !== 1 ? "s" : ""}`;
+  return `On sale ${formatOnSaleAt(startsAt)}`;
+};
+
+/** The sentence under a scheduled tier, spelling out the exact time. */
+export const onSaleNotice = (startsAt: Date): string =>
+  `Tickets for this tier go on sale ${formatOnSaleAt(startsAt)}.`;
+
+/**
+ * The most a buyer may put in the cart for one tier.
+ *
+ * `maxPerPerson` is a per-buyer cap and the seat count is a per-tier one; the
+ * cart is bounded by whichever bites first. Zero for anything not currently
+ * sellable, which is what disables the `+`.
+ */
+export const maxAddableTickets = (
+  /**
+   * `maxPerPerson` is widened to nullable HERE rather than on `ITicket`.
+   *
+   * The column is NOT NULL with a default, so `ITicket` is right about the
+   * database and must stay that way. But this function is handed payloads from
+   * two storefronts and older API builds, and its `?? seats` fallback exists
+   * precisely because the field can arrive absent. Typing the parameter for
+   * what it actually tolerates keeps that fallback reachable — and testable —
+   * without teaching the whole SDK that a non-null column is nullable.
+   */
+  ticket: Pick<ITicket, "quantity" | "sold" | "held" | "availableFrom"> & {
+    maxPerPerson?: number | null;
+  },
+  now: Date = new Date(),
+  /**
+   * 2.6b — seats of `held` reserved for this visitor by a waitlist offer.
+   *
+   * Deliberately NOT exempt from `maxPerPerson`: the offer decides how many
+   * seats are held, the artist's per-person cap decides how many one person may
+   * hold at all, and an offer is not a licence to exceed the second. The server
+   * enforces the cap on the same order either way, so exempting it here would
+   * only move the refusal to the card screen.
+   */
+  reservedForYou = 0,
+): number => {
+  if (isTicketScheduled(ticket, now)) return 0;
+  const seats = ticketSeatsAvailable(ticket, reservedForYou);
+  return Math.min(seats, ticket.maxPerPerson ?? seats);
+};

package/src/ui/headless/checkout/bundleCoupon.ts

@@ -23,13 +23,19 @@ export type BundleCouponSummary = {
    */
   appliedCoupon: { code: string; discountAmount: number } | null;
   /**
-   * The re-minted intent. Applying re-prices AND re-mints, so the payment
-   * element must move onto this secret — the previous one still quotes the
-   * pre-coupon amount. Null when there was no intent to replace (the bundle had
+   * The re-minted charge. Applying re-prices AND re-mints, so the payment
+   * element must move onto this session, because the previous one still quotes the
+   * pre-coupon amount. Null when there was nothing to replace (the bundle had
    * not started payment) or when the bundle settled for free.
+   *
+   * Exactly one of the two session fields is set: `paymentSecret` on Stripe,
+   * `accessCode` + `checkoutUrl` on Paystack. A Paystack re-mint carries no
+   * secret at all, which is why the gate below cannot test that field alone.
    */
   paymentUpdate: {
-    paymentSecret: string;
+    paymentSecret?: string;
+    accessCode?: string;
+    checkoutUrl?: string;
     paymentId: string;
     chargedAmount: number;
     chargedCurrency: string;
@@ -54,9 +60,11 @@ export function bundleCouponSummary(data: ApplyCheckoutCouponResult): BundleCoup
     // not claimed as one — `discountAmount` still reports the reduction.
     appliedCoupon: discountAmount > 0 && named ? { code: named.code, discountAmount } : null,
     paymentUpdate:
-      data.paymentSecret && data.paymentId
+      (data.paymentSecret || data.accessCode || data.checkoutUrl) && data.paymentId
         ? {
-            paymentSecret: data.paymentSecret,
+            paymentSecret: data.paymentSecret || undefined,
+            accessCode: data.accessCode,
+            checkoutUrl: data.checkoutUrl,
             paymentId: data.paymentId,
             chargedAmount: data.chargedAmount,
             chargedCurrency: data.chargedCurrency,