@tribe-nest/forge 3.21.0 → 3.22.0

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

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