@tribe-nest/forge 3.21.0 → 3.23.0

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/calendar/_tests/useAddToCalendar.spec.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect } from "vitest";
+import { buildAddToCalendarLinks } from "../useAddToCalendar";
+
+/**
+ * The Apple half of "add to calendar", which for a long time did not exist.
+ *
+ * Google and Microsoft publish TEMPLATE URLs — the whole event travels in the
+ * query string and no server is involved. Apple publishes nothing of the kind:
+ * Calendar takes a FILE, and Safari on iOS treats an https `.ics` as a file it
+ * cannot open. `webcal://` is the scheme iOS and macOS route to the Calendar
+ * app, so it is the only thing that makes an Apple option possible at all.
+ *
+ * This file is about the derivation, because that is where a mistake would be
+ * silent: a mangled scheme still renders a chip, and the failure only shows up
+ * on somebody's phone.
+ */
+describe("buildAddToCalendarLinks — the Apple routes", () => {
+  const base = { title: "Night Show", start: "2026-03-15T20:00:00.000Z" };
+
+  const ICS = "https://api.tribenest.co/public/calendar/events/abc/tok.ics";
+
+  it("offers neither route when the host has no .ics to point at", () => {
+    const links = buildAddToCalendarLinks(base)!;
+
+    // A site pinned to an older API build must degrade to the three template
+    // providers, not draw a dead Apple chip.
+    expect(links.ics).toBeNull();
+    expect(links.webcal).toBeNull();
+    expect(links.google).toContain("calendar.google.com");
+  });
+
+  it("derives webcal:// from the https address when only that is supplied", () => {
+    const links = buildAddToCalendarLinks({ ...base, icsUrl: ICS })!;
+
+    expect(links.ics).toBe(ICS);
+    // Scheme-only swap: the path, the id and the HMAC token must survive
+    // untouched, or the link resolves to a different document (or to nothing).
+    expect(links.webcal).toBe("webcal://api.tribenest.co/public/calendar/events/abc/tok.ics");
+  });
+
+  it("prefers the server's own webcal URL over the derivation", () => {
+    const links = buildAddToCalendarLinks({
+      ...base,
+      icsUrl: ICS,
+      webcalUrl: "webcal://cdn.example.com/other.ics",
+    })!;
+
+    // The API composes both; if it ever puts them on different hosts, the
+    // client must not quietly out-vote it.
+    expect(links.webcal).toBe("webcal://cdn.example.com/other.ics");
+  });
+
+  it("derives from http as well as https", () => {
+    const links = buildAddToCalendarLinks({ ...base, icsUrl: "http://localhost:8000/public/calendar/events/a/t.ics" })!;
+    expect(links.webcal).toBe("webcal://localhost:8000/public/calendar/events/a/t.ics");
+  });
+
+  it("refuses to invent a webcal URL from something that is not absolute", () => {
+    // `calendarFeedUrl` falls back to a bare PATH when `API_URL` is unset, and
+    // "webcal:///public/calendar/…" is not an address any client can resolve.
+    // Better no Apple option than a broken one.
+    const links = buildAddToCalendarLinks({ ...base, icsUrl: "/public/calendar/events/abc/tok.ics" })!;
+
+    expect(links.ics).toBe("/public/calendar/events/abc/tok.ics");
+    expect(links.webcal).toBeNull();
+  });
+
+  it("passes an already-webcal address through unchanged", () => {
+    const links = buildAddToCalendarLinks({ ...base, webcalUrl: "webcal://api.tribenest.co/a.ics" })!;
+    expect(links.webcal).toBe("webcal://api.tribenest.co/a.ics");
+    // No https form was supplied, so no download is offered.
+    expect(links.ics).toBeNull();
+  });
+
+  it("leaves the three template providers untouched by any of this", () => {
+    const withIcs = buildAddToCalendarLinks({ ...base, icsUrl: ICS })!;
+    const without = buildAddToCalendarLinks(base)!;
+
+    expect(withIcs.google).toBe(without.google);
+    expect(withIcs.outlook).toBe(without.outlook);
+    expect(withIcs.office365).toBe(without.office365);
+  });
+});

package/src/ui/headless/calendar/useAddToCalendar.ts

@@ -26,11 +26,29 @@ export type AddToCalendarInput = {
   /** Canonical page for the event; appended to the description body when present. */
   url?: string | null;
   /**
-   * Absolute URL to a downloadable `.ics` (what Apple Calendar / Outlook desktop
-   * want). Forge does not synthesize this — the host passes the endpoint it has.
-   * When absent, `ics` comes back `null` and no Apple option is offered.
+   * Absolute URL to a downloadable `.ics` — what Outlook desktop, Thunderbird
+   * and a Mac that would rather have the file all want.
+   *
+   * Forge does not synthesize this and cannot: the platform's `.ics` address
+   * carries a keyed HMAC, so it is deliberately not derivable from an event id.
+   * The host passes the field the API gave it (`calendarUrl`). When absent,
+   * `ics` comes back `null` and no download option is offered.
    */
   icsUrl?: string | null;
+  /**
+   * The same `.ics`, under `webcal://` — the API's `calendarWebcalUrl`.
+   *
+   * **This is the Apple route, and there is no other.** Apple publishes no
+   * "add to calendar" template URL the way Google and Microsoft do, which is
+   * exactly why every control in this product used to offer three providers and
+   * no Apple option. Safari on iOS treats an https `.ics` as a file it cannot
+   * open; the same address under `webcal:` is handed straight to Calendar.
+   *
+   * Optional, and derived from {@link icsUrl} when omitted — a host on an older
+   * API build that only carries the https form still gets a working Apple
+   * option, because the two differ only by scheme.
+   */
+  webcalUrl?: string | null;
 };
 
 export type AddToCalendarLinks = {
@@ -42,8 +60,14 @@ export type AddToCalendarLinks = {
   office365: string;
   /** Yahoo Calendar. */
   yahoo: string;
-  /** Pass-through of `icsUrl` — the Apple/desktop route. `null` when not supplied. */
+  /** Pass-through of `icsUrl` — the download route. `null` when not supplied. */
   ics: string | null;
+  /**
+   * The `webcal://` address, for the Apple option. Falls back to `icsUrl` with
+   * its scheme swapped, so supplying either one is enough. `null` when neither
+   * is available.
+   */
+  webcal: string | null;
   startsAt: Date;
   endsAt: Date;
 };
@@ -97,6 +121,20 @@ export function stripHtml(html: string, maxLength: number = MAX_DESCRIPTION_CHAR
 
 const enc = encodeURIComponent;
 
+/**
+ * The `webcal://` form, preferring what the host was given.
+ *
+ * The swap is scheme-only and is applied to an https address, never to an
+ * arbitrary string: a relative or already-`webcal:` URL is passed through
+ * untouched rather than being mangled into something a calendar client would
+ * refuse.
+ */
+function toWebcal(webcalUrl?: string | null, icsUrl?: string | null): string | null {
+  if (webcalUrl) return webcalUrl;
+  if (!icsUrl) return null;
+  return /^https?:\/\//i.test(icsUrl) ? icsUrl.replace(/^https?:\/\//i, "webcal://") : null;
+}
+
 /**
  * Build every provider URL for one calendar entry. Returns `null` when the
  * start is missing or unparseable — callers render nothing rather than a link
@@ -156,6 +194,7 @@ export function buildAddToCalendarLinks(input: AddToCalendarInput): AddToCalenda
       `&desc=${enc(body)}` +
       `&in_loc=${enc(location)}`,
     ics: input.icsUrl || null,
+    webcal: toWebcal(input.webcalUrl, input.icsUrl),
     startsAt,
     endsAt,
   };
@@ -177,6 +216,7 @@ export function useAddToCalendar(input: AddToCalendarInput | null | undefined):
   const location = input?.location;
   const url = input?.url;
   const icsUrl = input?.icsUrl;
+  const webcalUrl = input?.webcalUrl;
 
   return useMemo(() => {
     if (!start) return null;
@@ -189,6 +229,7 @@ export function useAddToCalendar(input: AddToCalendarInput | null | undefined):
       location,
       url,
       icsUrl,
+      webcalUrl,
     });
-  }, [title, start, end, defaultDurationMinutes, description, location, url, icsUrl]);
+  }, [title, start, end, defaultDurationMinutes, description, location, url, icsUrl, webcalUrl]);
 }

package/src/ui/headless/checkout/_tests/inventoryHold.spec.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from "vitest";
+import {
+  HOLD_EXPIRED_CODE,
+  formatHoldRemaining,
+  holdExpiredMessage,
+  holdMsRemaining,
+  isHoldExpiredError,
+} from "../inventoryHold";
+
+/**
+ * The inventory hold, as both rendering stacks read it.
+ *
+ * Every case here is a bug the checkout shipped with before this existed: a
+ * buyer told "sold out" for an item that was not sold out, a countdown drawn
+ * over an order that had no reservation at all, and a timer that read "0:00"
+ * for a whole second while the payment was still perfectly good.
+ *
+ * Pure, so they run with no provider tree — the same reason `bundleCoupon`'s
+ * helpers live outside the hook.
+ */
+
+const apiError = (data: Record<string, unknown>, status = 409) => ({ response: { status, data } });
+
+describe("isHoldExpiredError", () => {
+  it("recognises the 409 the hold endpoints throw", () => {
+    expect(isHoldExpiredError(apiError({ code: HOLD_EXPIRED_CODE, message: "…expired…" }))).toBe(true);
+  });
+
+  it("does NOT treat sold-out as an expired hold", () => {
+    // The whole point of splitting the error out: sold-out has no retry that
+    // can work, an expired hold usually does. Offering the wrong one is the
+    // regression this guards.
+    expect(isHoldExpiredError(apiError({ message: "This ticket is sold out." }, 400))).toBe(false);
+  });
+
+  it("does not fire on a bare 409 with no code", () => {
+    // A 409 is a generic conflict any future endpoint could answer with;
+    // switching on the status alone would offer a retry that cannot help.
+    expect(isHoldExpiredError(apiError({ message: "Conflict" }))).toBe(false);
+  });
+
+  it("is safe on the shapes an unexpected failure actually arrives as", () => {
+    expect(isHoldExpiredError(undefined)).toBe(false);
+    expect(isHoldExpiredError(null)).toBe(false);
+    expect(isHoldExpiredError(new Error("Network Error"))).toBe(false);
+    expect(isHoldExpiredError({})).toBe(false);
+  });
+});
+
+describe("holdExpiredMessage", () => {
+  it("prefers the API's own localised words", () => {
+    const message = "Your ticket reservation expired before payment finished.";
+    expect(holdExpiredMessage(apiError({ code: HOLD_EXPIRED_CODE, message }), "fallback")).toBe(message);
+  });
+
+  it("falls back only when the response carried nothing", () => {
+    expect(holdExpiredMessage(apiError({ code: HOLD_EXPIRED_CODE }), "fallback")).toBe("fallback");
+    expect(holdExpiredMessage(new Error("boom"), "fallback")).toBe("fallback");
+  });
+});
+
+describe("holdMsRemaining", () => {
+  const now = Date.parse("2026-08-09T12:00:00.000Z");
+
+  it("measures the window from now", () => {
+    expect(holdMsRemaining("2026-08-09T12:10:00.000Z", now)).toBe(600_000);
+  });
+
+  it("returns null — NOT zero — when no hold was taken", () => {
+    // `null` is "there is no reservation" (holds switched off for the profile,
+    // a digital-only cart, an already-settled free order); `0` is "a real one
+    // ran out". A surface that conflated them would draw an expired countdown
+    // on every order for every profile with the feature off.
+    expect(holdMsRemaining(null, now)).toBeNull();
+    expect(holdMsRemaining(undefined, now)).toBeNull();
+    expect(holdMsRemaining("", now)).toBeNull();
+  });
+
+  it("returns null for an unparseable instant rather than a bogus countdown", () => {
+    expect(holdMsRemaining("not-a-date", now)).toBeNull();
+  });
+
+  it("clamps a past instant to zero instead of counting up", () => {
+    expect(holdMsRemaining("2026-08-09T11:59:00.000Z", now)).toBe(0);
+  });
+});
+
+describe("formatHoldRemaining", () => {
+  it("renders m:ss", () => {
+    expect(formatHoldRemaining(600_000)).toBe("10:00");
+    expect(formatHoldRemaining(65_000)).toBe("1:05");
+    expect(formatHoldRemaining(9_000)).toBe("0:09");
+  });
+
+  it("rounds UP, so the clock only reads 0:00 when it is genuinely over", () => {
+    // Rounding down put "0:00" on screen for the last whole second of a hold
+    // that was still perfectly valid — a small lie the buyer acts on.
+    expect(formatHoldRemaining(1)).toBe("0:01");
+    expect(formatHoldRemaining(999)).toBe("0:01");
+    expect(formatHoldRemaining(0)).toBe("0:00");
+  });
+
+  it("grows to h:mm:ss for a long window", () => {
+    expect(formatHoldRemaining(3_600_000)).toBe("1:00:00");
+    expect(formatHoldRemaining(3_725_000)).toBe("1:02:05");
+  });
+
+  it("never renders a negative clock", () => {
+    expect(formatHoldRemaining(-5_000)).toBe("0:00");
+  });
+});

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,

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

@@ -0,0 +1,83 @@
+/**
+ * The inventory hold, as a buyer experiences it.
+ *
+ * The server reserves stock while a buyer is on the card form and reports when
+ * that reservation lapses (`holdExpiresAt`, ISO-8601, on every checkout-create
+ * and every `start-payment` response). When it lapses before the payment lands,
+ * `start-payment` answers **409 `INVENTORY_HOLD_EXPIRED`** — deliberately NOT
+ * the sold-out error, because "your reservation ran out" and "there are none
+ * left" lead the buyer to different next actions and only the first one has a
+ * retry that works.
+ *
+ * None of that was rendered anywhere. This module is the shared, provider-free
+ * half of rendering it, so both stacks (the client PWA and Forge's own styled
+ * drop-ins) count the same clock and read the same error.
+ *
+ * Everything here is pure — no React, no provider tree — so it is unit-testable
+ * on its own, the same reason `bundleCoupon.ts` sits beside it.
+ */
+
+/** The machine-readable code the API stamps on an expired-hold refusal. */
+export const HOLD_EXPIRED_CODE = "INVENTORY_HOLD_EXPIRED";
+
+type MaybeApiError = {
+  response?: { status?: number; data?: { code?: string; message?: string } };
+};
+
+/**
+ * Is this failure "your reservation lapsed" rather than anything else?
+ *
+ * Switches on `code`, never on prose and never on the bare 409 — a 409 alone is
+ * a generic conflict a future endpoint could reuse, and treating one as an
+ * expired hold would offer a retry that cannot help.
+ */
+export function isHoldExpiredError(error: unknown): boolean {
+  return (error as MaybeApiError)?.response?.data?.code === HOLD_EXPIRED_CODE;
+}
+
+/**
+ * The API's own words for a lapsed hold, already localised server-side
+ * (`errors.order.hold_expired` / `errors.event.hold_expired`).
+ *
+ * The fallback is only reached if the response carried no message at all; it is
+ * never used to *replace* the server's message, which is the one that names the
+ * right noun ("basket" vs "tickets").
+ */
+export function holdExpiredMessage(error: unknown, fallback: string): string {
+  return (error as MaybeApiError)?.response?.data?.message || fallback;
+}
+
+/**
+ * Milliseconds until the hold lapses, or `null` when there is no hold.
+ *
+ * `null` and `0` are different facts and the UI must not conflate them:
+ * `holdExpiresAt` is absent for a free/already-settled order and for every
+ * profile with the holds switch off, and inventing a countdown there would
+ * promise a reservation nobody took. Zero means a real hold that has run out.
+ *
+ * Clamped at zero so a stale or clock-skewed instant reads as lapsed rather
+ * than as a negative timer.
+ */
+export function holdMsRemaining(holdExpiresAt: string | null | undefined, now: number): number | null {
+  if (!holdExpiresAt) return null;
+  const ms = Date.parse(holdExpiresAt);
+  if (Number.isNaN(ms)) return null;
+  return Math.max(0, ms - now);
+}
+
+/**
+ * `m:ss` for the countdown, and `h:mm:ss` above an hour.
+ *
+ * Rounds UP, so a hold with 1ms left reads "0:01" and the timer only shows
+ * "0:00" at the instant it is genuinely over — a countdown that sits on zero
+ * for a whole second while payment is still accepted is a small lie the buyer
+ * acts on.
+ */
+export function formatHoldRemaining(msRemaining: number): string {
+  const total = Math.ceil(Math.max(0, msRemaining) / 1000);
+  const seconds = total % 60;
+  const minutes = Math.floor(total / 60) % 60;
+  const hours = Math.floor(total / 3600);
+  const mm = hours > 0 ? String(minutes).padStart(2, "0") : String(minutes);
+  return `${hours > 0 ? `${hours}:` : ""}${mm}:${String(seconds).padStart(2, "0")}`;
+}