@riverbankcms/sdk 0.135.1 → 0.137.0

package/dist/client/bookings.mjs

@@ -2565,6 +2565,10 @@ const EVENTS = {
 	registrationStatus: {
 		path: "/public/sites/{siteId}/events/registration-status",
 		method: "GET"
+	},
+	checkoutReturn: {
+		path: "/public/sites/{siteId}/events/checkout-return",
+		method: "POST"
 	}
 };
 const WHOLE_SERIES = {
@@ -2834,10 +2838,11 @@ function encodePublicProductCategorySelector(selector) {
 * Error thrown when an API request fails
 */
 var BlockApiError = class extends Error {
-	constructor(message, status, code) {
+	constructor(message, status, code, tag) {
 		super(message);
 		this.status = status;
 		this.code = code;
+		this.tag = tag;
 		this.name = "BlockApiError";
 	}
 };
@@ -2869,7 +2874,8 @@ function getBlockApiErrorDetails(data) {
 	const nestedError = isRecord$7(data.error) ? data.error : void 0;
 	return {
 		message: typeof nestedError?.message === "string" ? nestedError.message : typeof data.message === "string" ? data.message : void 0,
-		code: typeof nestedError?.code === "string" ? nestedError.code : typeof data.code === "string" ? data.code : void 0
+		code: typeof nestedError?.code === "string" ? nestedError.code : typeof data.code === "string" ? data.code : void 0,
+		tag: typeof nestedError?.tag === "string" ? nestedError.tag : void 0
 	};
 }
 function buildUnexpectedJsonResponseMessage(parseResult) {
@@ -2888,7 +2894,8 @@ async function extractErrorDetails(response) {
 			const details = getBlockApiErrorDetails(parseResult.value);
 			return {
 				message: details.message ?? fallbackMessage,
-				code: details.code
+				code: details.code,
+				tag: details.tag
 			};
 		}
 		case "invalid-json": return { message: `${fallbackMessage} (received invalid JSON)` };
@@ -2985,7 +2992,7 @@ function createBlockApi(config) {
 			const response = await fetch(url, fetchOptions);
 			if (!response.ok) {
 				const details = await extractErrorDetails(response);
-				throw new BlockApiError(details.message, response.status, details.code);
+				throw new BlockApiError(details.message, response.status, details.code, details.tag);
 			}
 			const json = await parseJsonApiResponse(response);
 			if (isApiSuccessResponse(json)) return json.data;
@@ -3161,6 +3168,14 @@ function createBlockApi(config) {
 				skipDedup: true
 			});
 		},
+		async resolveEventCheckoutReturn(data) {
+			const sid = requireSiteId();
+			const path = buildPath(EVENTS.checkoutReturn.path, { siteId: sid });
+			return request(EVENTS.checkoutReturn, {
+				path,
+				body: data
+			});
+		},
 		async resolveWaitlistClaim(data) {
 			const sid = requireSiteId();
 			const path = buildPath(WHOLE_SERIES.waitlistClaimResolve.path, { siteId: sid });
@@ -3811,6 +3826,18 @@ function isRecord$6(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 //#endregion
+//#region ../core/src/money-input.ts
+function unsafeAsNonNegativeCents(value) {
+	return value;
+}
+/**
+* Normalizes a derived amount to non-negative whole cents. This intentionally
+* clamps negatives to zero; use parseNonNegativeCents for validation.
+*/
+function toNonNegativeCents(value) {
+	return unsafeAsNonNegativeCents(Math.max(0, Math.trunc(value)));
+}
+//#endregion
 //#region ../core/src/booking-flexible-balance.ts
 function clampFlexibleBalanceConfiguredAmount(amountCents, totalAmountCents) {
 	return Math.max(0, Math.min(amountCents, totalAmountCents));
@@ -8771,6 +8798,11 @@ const gradientConfigSchema = z.object({
 	position: z.string().optional(),
 	stops: z.array(gradientStopSchema).min(2)
 });
+const gradientsSchema = z.object({
+	button: z.string().min(1).nullable().optional(),
+	hero: z.string().min(1).nullable().optional(),
+	background: z.string().min(1).nullable().optional()
+});
 //#endregion
 //#region ../theme-core/src/interactive/baseSchema.ts
 /**
@@ -9383,12 +9415,8 @@ const legacyHeaderVariantValues = Object.keys(legacyHeaderVariants);
 * `@riverbankcms/api` is `z.input<typeof themeSchema>`, so a widened input here
 * would leak straight into a public type.
 *
-* Not every read of a persisted theme goes through the schema:
-* `resolveRuntimeTheme` in
-* `apps/dashboard/src/server/services/sites/runtimeSiteResponse.ts` returns the
-* raw database JSON asserted as `Theme` with no parse, so a theme still
-* carrying a legacy spelling reaches the theme editor un-aliased. That gap
-* predates this alias and is harmless while persisted usage is zero.
+* Persisted runtime themes are admitted through `parseThemeForPersistence`
+* before reaching consumers, so legacy spellings normalize at that boundary.
 */
 const headerVariantWithLegacyAliasSchema = z.enum([...headerVariantValues, ...legacyHeaderVariantValues]).transform((value) => value in legacyHeaderVariants ? legacyHeaderVariants[value] : value);
 const BREAKPOINT_LG = 1024;
@@ -9440,11 +9468,30 @@ const headerContainerSchema = z.object({
 	tint: z.string().nullable().optional(),
 	opacity: z.number().min(0).max(1).default(.12)
 }).optional();
-const headerInteractionPaletteSchema = z.enum([
+//#endregion
+//#region ../theme-core/src/header/interactionPalette.ts
+/**
+* The palettes that fill the nav link with a colour on hover and focus. Each
+* one names a background/foreground token pair.
+*/
+const headerInteractionPillPaletteValues = [
 	"primary",
 	"secondary",
 	"accent"
-]);
+];
+/**
+* "No pill": the nav link keeps whatever hover treatment its recipe compiled,
+* and the palette step writes nothing at all (#1318 Phase 4c decision 2).
+*
+* It exists because "a colour change on hover, no filled background" was not
+* expressible in the vocabulary, and it is what
+* `anna-raven-therapy-and-yoga` and `kirtan-lucy` have rendered since before
+* the palette existed. Without it those two rows can only be classified as a
+* conscious visual change.
+*/
+const headerInteractionQuietPalette = "quiet";
+const headerInteractionPaletteValues = [...headerInteractionPillPaletteValues, headerInteractionQuietPalette];
+const headerInteractionPaletteSchema = z.enum(headerInteractionPaletteValues);
 //#endregion
 //#region ../theme-core/src/boxBackgroundSchema.ts
 const boxBackgroundOverlaySchema = z.preprocess(normalizeAuthoringOpacity, z.discriminatedUnion("type", [
@@ -9847,7 +9894,6 @@ const navFontWeight = z.enum([
 	"bold"
 ]);
 const headerMaxWidth = z.enum(["container", "full"]);
-const headerBarFrame = z.enum(["full-bleed", "inset-shell"]);
 const headerBorderSchema = componentBorderSchema.extend({ position: z.enum([
 	"bottom",
 	"top",
@@ -9876,12 +9922,6 @@ const headerLogoTextSchema = z.object({
 	]).optional(),
 	hideOnShrink: z.boolean().optional()
 }).optional();
-const navEffectsSchema = z.object({
-	underlineGradient: z.boolean().default(false),
-	glow: z.boolean().default(false),
-	glowColor: z.string().optional(),
-	neumorphic: z.boolean().default(false)
-}).optional();
 const dropdownStyleSchema = z.object({
 	background: themeColorTokenSchema.default("surface"),
 	textColor: themeColorTokenSchema.default("text"),
@@ -9972,10 +10012,8 @@ const headerSchema = z.object({
 	variant: headerVariantWithLegacyAliasSchema,
 	positioning: headerPositioning,
 	shrinkOnScroll: z.boolean(),
-	maxWidth: headerMaxWidth,
-	barFrame: headerBarFrame.optional(),
+	maxWidth: headerMaxWidth.default("container"),
 	scrollTreatment: headerScrollTreatmentSchema,
-	logoOverride: mediaSchema.nullable().optional(),
 	background: headerBackgroundSchema.default({
 		type: "color",
 		color: "surface"
@@ -9987,13 +10025,11 @@ const headerSchema = z.object({
 	navFontRole: z.enum(["body", "heading"]).optional(),
 	navTextSize: navLinkStyleSchema.shape.textSize,
 	interactionPalette: headerInteractionPaletteSchema.optional(),
-	navPlacement: z.enum(["end", "center"]).optional(),
 	container: headerContainerSchema,
 	border: headerBorderSchema,
 	shadow: componentShadowSchema.optional(),
 	logo: logoStyleSchema,
 	logoText: headerLogoTextSchema,
-	navEffects: navEffectsSchema,
 	navContainer: navContainerSchema,
 	navLinkStyle: navLinkStyleSchema.optional(),
 	ctaGap: headerCtaGapSchema.optional(),
@@ -10175,11 +10211,6 @@ const bodyTextSchema = z.object({ intro: z.object({
 	paragraphSize: bodyTextIntroTypographySizeSchema.optional(),
 	headingSize: bodyTextIntroTypographySizeSchema.optional()
 }).optional() }).optional();
-const gradientsSchema = z.object({
-	button: z.string().min(1).nullable().optional(),
-	hero: z.string().min(1).nullable().optional(),
-	background: z.string().min(1).nullable().optional()
-});
 /**
 * Testimonial quote-mark treatment, owned by the site style (analogous to the
 * accordion icon). `style` is the coarse selector; the optional fields fine-tune
@@ -14303,7 +14334,113 @@ const BookingFormClient$1 = ({ siteId: siteIdProp, render }) => {
 	});
 };
 //#endregion
-//#region ../blocks/src/system/runtime/nodes/events/shared/destination.ts
+//#region ../blocks/src/system/runtime/nodes/event-registration/registrationErrorRecovery.ts
+function resolveRegistrationRecoveryAction(step, action) {
+	if (step === "payment-failed") return "payment-options";
+	if (step === "verifying-payment" || step === "verifying-timeout" || step === "redirecting") return "payment-status";
+	return action;
+}
+function canRecoverToWaitlist(eligibility) {
+	return Boolean(eligibility?.isFull && eligibility.canJoinWaitlist);
+}
+function shouldRefreshAfterRegistrationError(step, action, enabled) {
+	return enabled || step === "error" && action === "places";
+}
+function resetRegistrationAfterExpiry(input) {
+	input.dispatchFlow({
+		type: "reset",
+		hasPreSelectedContext: input.hasPreSelectedContext
+	});
+	input.setSelectedTicketLines([]);
+	input.setSelectedSlidingAmountInput("");
+	const mode = input.preSelectedEvent?.deliveryMode;
+	input.setSelectedAttendanceMode(mode === "online" || mode === "in_person" ? mode : null);
+	input.setErrorMessage("");
+	input.setPendingRegistrationReference(null);
+}
+/** Recovery never starts another payment. Unknown payment outcomes go to the portal. */
+function recoverRegistrationError(action, handlers) {
+	switch (action) {
+		case "none": return;
+		case "portal":
+		case "payment-status":
+			window.location.assign("/portal");
+			return;
+		case "event":
+			window.location.assign(window.location.pathname);
+			return;
+		case "retry":
+			window.location.reload();
+			return;
+		case "details":
+			handlers.clearError();
+			handlers.setStep("enter-details");
+			return;
+		case "payment-options":
+		case "places":
+			handlers.refreshOptions();
+			handlers.clearError();
+			handlers.setStep(action === "places" ? handlers.canJoinWaitlist ? "enter-details" : "select-tickets" : "select-payment");
+			return;
+		case "start":
+			handlers.refreshOptions();
+			handlers.reset();
+			return;
+	}
+}
+//#endregion
+//#region ../blocks/src/system/runtime/nodes/events/domain/capacity.ts
+/**
+* Compute remaining spots for an event from `availableSpots` with a fallback
+* to `capacity - registeredCount`. Returns `{ available: null, isFull: false }`
+* for uncapped events so call sites can render no capacity indicator at all.
+*
+* The single source of truth for capacity math across event cards, agenda
+* rows, and timetable cells — keep wording variations in the call sites.
+*/
+function getEventAvailability(event) {
+	if (event.capacity == null) return {
+		available: null,
+		isFull: false
+	};
+	const available = event.availableSpots ?? event.capacity - event.registeredCount;
+	if (available <= 0) return {
+		available: 0,
+		isFull: true
+	};
+	return {
+		available,
+		isFull: false
+	};
+}
+/**
+* Pick the capacity row a booking decision should read: the selected
+* attendance mode's availability when the visitor has chosen one and the
+* event publishes it, otherwise the event-level aggregate.
+*
+* The mode row is used wholesale. A mode with `capacity: null` on a capped
+* event is uncapped *by design*: the registration write path applies the
+* same rule via `getEffectiveOccurrenceCapacityForAttendanceMode`, so falling
+* back to the event's `availableSpots` here would block bookings the server
+* accepts. (Waitlist claims are still occurrence-scoped; see issue 1377.)
+*/
+function selectEventCapacitySource(event, attendanceMode) {
+	if (!attendanceMode) return event;
+	return (event.attendanceModes ?? []).find((mode) => mode.mode === attendanceMode) ?? event;
+}
+/**
+* Whether the visitor's next step is the waitlist: the source is full *and*
+* a waitlist is open. The one place this is decided — cards, rows, the
+* wizard's steps and its action bar all route through here so they agree,
+* including for producers that omit `availableSpots` and rely on the
+* `capacity - registeredCount` fallback.
+*/
+function canJoinEventWaitlist(event, options) {
+	const source = selectEventCapacitySource(event, options?.attendanceMode);
+	return getEventAvailability(source).isFull && source.waitlistEnabled === true;
+}
+//#endregion
+//#region ../blocks/src/system/runtime/nodes/events/domain/destination.ts
 function isRecord$2(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -14321,7 +14458,7 @@ function resolveRuntimeEventDestination(event) {
 	};
 }
 //#endregion
-//#region ../blocks/src/system/runtime/nodes/events/shared/pricing.ts
+//#region ../blocks/src/system/runtime/nodes/events/domain/pricing.ts
 const DEFAULT_EVENT_CURRENCY = "USD";
 function resolveRuntimeEventPricing(event) {
 	if (isPublicEventPricing(event.pricing)) return event.pricing;
@@ -14831,11 +14968,11 @@ function useEligibilityWithDeps(params, deps) {
 					type: "resolved",
 					eligibility: transformRegistrationOptionsResponse(result)
 				});
-			} catch (err) {
+			} catch {
 				if (cancelled || requestIdRef.current !== requestId) return;
 				dispatch({
 					type: "failed",
-					message: err instanceof Error ? err.message : "Failed to check eligibility"
+					message: "We couldn’t load the booking options for this event. Please refresh this page and try again. If this keeps happening, contact the organiser for help."
 				});
 			}
 		}
@@ -14847,6 +14984,7 @@ function useEligibilityWithDeps(params, deps) {
 	}, [
 		api,
 		params.enabled,
+		params.refreshKey,
 		params.subject?.kind,
 		params.subject?.kind === "occurrence" ? params.subject.occurrenceId : params.subject?.eventSeriesId,
 		params.attendanceMode,
@@ -14956,8 +15094,122 @@ function logoutPortal(anchorId) {
 	form.submit();
 }
 //#endregion
+//#region ../commerce/src/purchase/checkoutSessionMetadata.ts
+const datedOfferingSharedEngineMetadataShape = {
+	datedOfferingEngineContractVersion: z.literal("shared_v1"),
+	datedOfferingEngineRouteKind: z.literal("shared_whole_series_registration"),
+	datedOfferingCapacityHoldId: z.string().uuid(),
+	datedOfferingCapacityHoldAuditRef: z.string().uuid(),
+	customerId: z.string().uuid(),
+	eventSeriesId: z.string().uuid()
+};
+z.object(datedOfferingSharedEngineMetadataShape);
+const orderCheckoutSessionMetadataBaseShape = {
+	type: z.literal("order"),
+	site_id: z.string().uuid(),
+	order_id: z.string().uuid().optional(),
+	customer_email: z.string().email(),
+	customer_name: z.string().optional(),
+	product_id: z.string().uuid().optional(),
+	attendee_id: z.string().uuid().optional(),
+	occurrence_id: z.string().uuid().optional(),
+	tickets_count: z.string().optional(),
+	notes: z.string().optional(),
+	discount_redemption_id: z.string().uuid().optional(),
+	discount_code_id: z.string().uuid().optional(),
+	discount_code: z.string().optional(),
+	discount_public_label: z.string().optional(),
+	credit_reservation_id: z.string().uuid().optional(),
+	credit_reserved_cents: z.string().optional(),
+	discount_code_amount_cents: z.string().optional(),
+	order_payment_reason: z.enum([
+		"instalment_payoff",
+		"flexible_balance_initial",
+		"flexible_balance_paydown"
+	]).optional(),
+	order_payment_plan_id: z.string().uuid().optional(),
+	order_flexible_balance_contract_id: z.string().uuid().optional()
+};
+const absentDatedOfferingSharedEngineMetadataShape = {
+	datedOfferingEngineContractVersion: z.never().optional(),
+	datedOfferingEngineRouteKind: z.never().optional(),
+	datedOfferingCapacityHoldId: z.never().optional(),
+	datedOfferingCapacityHoldAuditRef: z.never().optional(),
+	customerId: z.never().optional(),
+	eventSeriesId: z.never().optional()
+};
+const LegacyOrderCheckoutSessionMetadataSchema = z.object({
+	...orderCheckoutSessionMetadataBaseShape,
+	...absentDatedOfferingSharedEngineMetadataShape
+});
+const SharedDatedOfferingOrderCheckoutSessionMetadataSchema = z.object({
+	...orderCheckoutSessionMetadataBaseShape,
+	...datedOfferingSharedEngineMetadataShape
+});
+z.union([SharedDatedOfferingOrderCheckoutSessionMetadataSchema, LegacyOrderCheckoutSessionMetadataSchema]);
+toNonNegativeCents(0);
+//#endregion
+//#region ../commerce/src/purchase/event-registration-errors.ts
+const eventRegistrationErrors = {
+	registrationClosed: {
+		message: "Booking is currently closed for this event. Please contact the organiser if you’d like to find out more.",
+		action: "none"
+	},
+	paymentUncertain: {
+		message: "We’re checking your booking and payment. Please don’t try to book again yet. If you’ve already paid, you don’t need to pay again.",
+		action: "payment-status"
+	},
+	paymentPageUnavailable: {
+		message: "We couldn’t open the payment page. Please refresh this page and try again. If this keeps happening, contact the organiser for help.",
+		action: "retry"
+	},
+	paymentUnavailable: {
+		message: "Online payment is not available for this event right now. Please contact the organiser for help with booking.",
+		action: "none"
+	},
+	capacityChanged: {
+		message: "Sorry, there aren’t enough places left for your selection. Please check the available places and choose again.",
+		action: "places"
+	},
+	selectionChanged: {
+		message: "The booking options for this event have changed. Please check the latest options and choose your places again.",
+		action: "places"
+	},
+	registrationPreparationChanged: {
+		message: "The booking options for this event have changed. Please check the latest options and choose your places again.",
+		action: "places"
+	},
+	registrationAlreadyExists: {
+		message: "You already have a booking for this event. Please check your bookings to see its status. If you need help, contact the organiser.",
+		action: "portal"
+	},
+	holdExpired: {
+		message: "Your reservation has timed out. Please check availability and choose your places again.",
+		action: "start"
+	},
+	waitlistUnavailable: {
+		message: "Sorry, the waiting list place offered in this invitation is no longer available. Please check the event for available places or contact the organiser for help.",
+		action: "event"
+	},
+	paymentContextMismatch: {
+		message: "The payment options for this event have changed. Please check the latest options before continuing.",
+		action: "payment-options"
+	},
+	idempotencyConflict: {
+		message: "You’ve already started booking this event. Please finish in the other tab if it’s still open, or check your booking status before starting again.",
+		action: "portal"
+	},
+	invalidCommitInput: {
+		message: "We couldn’t accept your booking details. Please check the information you entered and try again. If this keeps happening, contact the organiser for help.",
+		action: "details"
+	}
+};
+function parseEventRegistrationErrorReason(value) {
+	return typeof value === "string" && Object.prototype.hasOwnProperty.call(eventRegistrationErrors, value) ? value : null;
+}
+//#endregion
 //#region ../blocks/src/system/runtime/shared/useWaitlistClaim.state.ts
-const DEFAULT_WAITLIST_CLAIM_ERROR = "Failed to resolve waitlist claim";
+const DEFAULT_WAITLIST_CLAIM_ERROR = "Online booking is unavailable right now. Please contact the organiser for help with booking.";
 function createInitialWaitlistClaimState(hasToken) {
 	return hasToken ? { kind: "resolving" } : { kind: "idle" };
 }
@@ -14973,14 +15225,13 @@ function waitlistClaimReducer(_state, action) {
 	}
 }
 function toWaitlistClaimResolveFailure(error) {
-	const message = error instanceof Error ? error.message : DEFAULT_WAITLIST_CLAIM_ERROR;
 	if (isUnauthorizedBlockApiError(error)) return {
 		kind: "portal-login-required",
-		message
+		message: "Please log in to continue with your waiting list invitation."
 	};
 	return {
 		kind: "error",
-		message
+		message: hasStatus(error) && (error.status === 404 || error.status === 409 || error.status === 410) ? eventRegistrationErrors.waitlistUnavailable.message : DEFAULT_WAITLIST_CLAIM_ERROR
 	};
 }
 function isUnauthorizedBlockApiError(error) {
@@ -15341,47 +15592,136 @@ function cleanupStaleRegistrations() {
 //#region ../blocks/src/system/runtime/nodes/event-registration/useEventRegistrationStripeReturn.ts
 const eventRegistrationStripeReturnDeps = {
 	usePaymentVerification,
-	consumeReturnParams: () => consumeSearchParams(["registration", EVENT_REGISTRATION_CHECKOUT_ATTEMPT_PARAM]),
+	readReturnParams: () => {
+		const params = new URLSearchParams(window.location.search);
+		return {
+			registration: params.get("registration"),
+			registration_attempt: params.get(EVENT_REGISTRATION_CHECKOUT_ATTEMPT_PARAM),
+			session_id: params.get("session_id")
+		};
+	},
+	clearReturnParams: () => {
+		consumeSearchParams([
+			"registration",
+			EVENT_REGISTRATION_CHECKOUT_ATTEMPT_PARAM,
+			"session_id"
+		]);
+	},
 	scrollToBlock,
 	cleanupStaleRegistrations,
 	clearPendingRegistration,
 	getPendingRegistration
 };
+function restorePendingPresentation(options, pending) {
+	options.setFormData(pending.formData);
+	options.setTicketSelections(pending.ticketSelections);
+	options.setTicketsCount(getTicketSelectionTotal(pending.ticketSelections));
+	if (pending.selectedEventId) {
+		const event = options.events.find((item) => item.selectionId === pending.selectedEventId) ?? null;
+		if (event) options.setSelectedEvent(event);
+	}
+	options.setSelectedAttendanceMode(pending.selectedAttendanceMode ?? null);
+	options.setPaymentSelection(pending.paymentSelection);
+}
+function showReturnReconciliation(options, message) {
+	options.setErrorMessage(message);
+	options.setStep("verifying-timeout");
+}
+function checkoutReturnCommand(params) {
+	const checkoutAttemptId = params.registration_attempt;
+	if (!checkoutAttemptId) return null;
+	if (params.registration === "cancelled") return {
+		kind: "abandon",
+		checkoutAttemptId
+	};
+	if (params.registration === "success" && params.session_id) return {
+		kind: "resolveSuccess",
+		checkoutAttemptId,
+		sessionId: params.session_id
+	};
+	return null;
+}
+async function handleCheckoutReturn(options, deps, checkoutAttemptIdRef) {
+	deps.cleanupStaleRegistrations();
+	const params = deps.readReturnParams();
+	if (params.registration !== "cancelled" && params.registration !== "success") return "settled";
+	deps.scrollToBlock(EVENT_REGISTRATION_ANCHOR_ID);
+	const siteId = options.api.config.siteId;
+	const command = checkoutReturnCommand(params);
+	if (!siteId) return "settled";
+	if (!command) {
+		showReturnReconciliation(options, "We’re checking your booking and payment. Please don’t try to book again yet. If you’ve already paid, you don’t need to pay again.");
+		return "settled";
+	}
+	const { checkoutAttemptId } = command;
+	const pending = deps.getPendingRegistration(siteId, checkoutAttemptId);
+	checkoutAttemptIdRef.current = checkoutAttemptId;
+	if (pending) restorePendingPresentation(options, pending);
+	options.setStep("verifying-payment");
+	try {
+		const outcome = await options.api.resolveEventCheckoutReturn(command);
+		switch (outcome.kind) {
+			case "resolved":
+				deps.clearReturnParams();
+				options.setPendingRegistrationReference(outcome.reference);
+				options.setStep("verifying-payment");
+				return "settled";
+			case "abandoned":
+				deps.clearReturnParams();
+				options.setErrorMessage("Your payment was cancelled. You can choose a payment option and try again.");
+				options.setStep("select-payment");
+				return "settled";
+			case "notFound":
+				if (params.registration === "cancelled" && (options.registrationSubject?.kind === "occurrence" || pending?.reference.scope === "occurrence")) {
+					deps.clearReturnParams();
+					options.setErrorMessage("Your payment was cancelled. You can choose a payment option and try again.");
+					options.setStep("select-payment");
+					return "settled";
+				}
+				showReturnReconciliation(options, "We’re checking your booking and payment. Please don’t try to book again yet. If you’ve already paid, you don’t need to pay again.");
+				return "settled";
+			case "reconciliationRequired": break;
+		}
+		showReturnReconciliation(options, "We’re checking your booking and payment. Please don’t try to book again yet. If you’ve already paid, you don’t need to pay again.");
+	} catch {
+		showReturnReconciliation(options, "We couldn’t check your payment just now. Please check again in a moment. Don’t make another booking while we’re checking.");
+	}
+	return "retryable";
+}
 function useEventRegistrationStripeReturn(options) {
 	return useEventRegistrationStripeReturnWithDeps(options, eventRegistrationStripeReturnDeps);
 }
 function useEventRegistrationStripeReturnWithDeps(options, deps) {
-	const { api, events, pendingRegistrationReference, setErrorMessage, setFormData, setPaymentSelection, setPendingRegistrationReference, setRegistrationResult, setSelectedEvent, setSelectedAttendanceMode, setTicketSelections, setStep, setTicketsCount, step } = options;
+	const { api, pendingRegistrationReference, setErrorMessage, setRegistrationResult, setStep, step } = options;
 	const checkoutAttemptIdRef = useRef(null);
+	const lookupInFlightRef = useRef(false);
+	const [lookupState, setLookupState] = useState("settled");
+	const resolveReturn = useCallback(async () => {
+		if (lookupInFlightRef.current) return;
+		lookupInFlightRef.current = true;
+		setLookupState("loading");
+		try {
+			setLookupState(await handleCheckoutReturn(options, deps, checkoutAttemptIdRef));
+		} finally {
+			lookupInFlightRef.current = false;
+		}
+	}, [options, deps]);
 	const verificationConfig = useMemo(() => step === "verifying-payment" && pendingRegistrationReference ? { reference: pendingRegistrationReference } : null, [step, pendingRegistrationReference]);
 	const verification = deps.usePaymentVerification(verificationConfig);
-	useEffect(() => {
-		deps.cleanupStaleRegistrations();
-		const returnParams = deps.consumeReturnParams();
-		const registrationStatus = returnParams.registration;
-		if (registrationStatus !== "cancelled" && registrationStatus !== "success") return;
-		deps.scrollToBlock(EVENT_REGISTRATION_ANCHOR_ID);
-		const siteId = api.config.siteId;
-		if (!siteId) return;
-		const checkoutAttemptId = returnParams[EVENT_REGISTRATION_CHECKOUT_ATTEMPT_PARAM];
-		if (!checkoutAttemptId) return;
-		const pending = deps.getPendingRegistration(siteId, checkoutAttemptId);
-		if (!pending) return;
-		checkoutAttemptIdRef.current = checkoutAttemptId;
-		setFormData(pending.formData);
-		setTicketSelections(pending.ticketSelections);
-		setTicketsCount(getTicketSelectionTotal(pending.ticketSelections));
-		if (pending.selectedEventId) {
-			const event = events.find((e) => e.selectionId === pending.selectedEventId) ?? null;
-			if (event) setSelectedEvent(event);
-		}
-		setSelectedAttendanceMode(pending.selectedAttendanceMode ?? null);
-		setPaymentSelection(pending.paymentSelection);
-		if (registrationStatus === "cancelled") setStep("select-payment");
-		else if (registrationStatus === "success") {
-			setPendingRegistrationReference(pending.reference);
+	const hasVerificationTimeout = step === "verifying-timeout" && pendingRegistrationReference !== null;
+	const retry = useCallback(() => {
+		if (hasVerificationTimeout) {
 			setStep("verifying-payment");
+			return;
 		}
+		verification.retry();
+	}, [
+		hasVerificationTimeout,
+		setStep,
+		verification.retry
+	]);
+	useEffect(() => {
+		resolveReturn();
 	}, []);
 	useEffect(() => {
 		if (verification.status === "completed") {
@@ -15391,7 +15731,7 @@ function useEventRegistrationStripeReturnWithDeps(options, deps) {
 			setRegistrationResult({ status: "confirmed" });
 			setStep("success");
 		} else if (verification.status === "failed") {
-			setErrorMessage(verification.error ?? "Payment failed. Please try again.");
+			setErrorMessage("Please try again or choose another payment option. If this keeps happening, contact the organiser for help.");
 			setStep("payment-failed");
 		} else if (verification.status === "timeout") setStep("verifying-timeout");
 	}, [
@@ -15404,7 +15744,22 @@ function useEventRegistrationStripeReturnWithDeps(options, deps) {
 		setRegistrationResult,
 		setStep
 	]);
-	return verification;
+	return {
+		...verification,
+		status: hasVerificationTimeout ? "timeout" : verification.status,
+		retry,
+		retryReturn: lookupState === "retryable" ? () => {
+			resolveReturn();
+		} : void 0
+	};
+}
+//#endregion
+//#region ../blocks/src/system/runtime/nodes/event-registration/registrationErrorPresentation.ts
+function registrationErrorPresentation(error) {
+	const reason = error instanceof BlockApiError ? parseEventRegistrationErrorReason(error.tag) : null;
+	if (reason) return eventRegistrationErrors[reason];
+	if (error instanceof BlockApiError && error.status < 500) return eventRegistrationErrors.invalidCommitInput;
+	return eventRegistrationErrors.paymentUncertain;
 }
 //#endregion
 //#region ../blocks/src/system/runtime/nodes/event-registration/useEventRegistrationSubmit.ts
@@ -15464,7 +15819,7 @@ function useEventRegistrationSubmitWithDeps(options, deps) {
 		options.setStep("submitting");
 		try {
 			const prepared = prepareSubmitContext(options, target, method, passId, membershipId, selection);
-			if (prepared.subject.kind === "wholeSeries" && method === "stripe") return submitWholeSeriesCheckout(options, deps, {
+			if (prepared.subject.kind === "wholeSeries" && method === "stripe") return await submitWholeSeriesCheckout(options, deps, {
 				...prepared,
 				subject: prepared.subject
 			}, submitOptions);
@@ -15485,7 +15840,7 @@ function useEventRegistrationSubmitWithDeps(options, deps) {
 				claimToken: options.claimToken ?? void 0,
 				guests: prepared.guestsPayload
 			});
-			if (needsOccurrenceCheckout(result, method)) return submitOccurrenceCheckout(options, deps, prepared, result, method, submitOptions);
+			if (needsOccurrenceCheckout(result, method)) return await submitOccurrenceCheckout(options, deps, prepared, result, method, submitOptions);
 			options.setRegistrationResult(toRegistrationResult(result));
 			options.setStep("success");
 			return {
@@ -15493,7 +15848,8 @@ function useEventRegistrationSubmitWithDeps(options, deps) {
 				outcome: { kind: "completed" }
 			};
 		} catch (error) {
-			const message = error instanceof Error ? error.message : "Registration failed";
+			const { message, action } = registrationErrorPresentation(error);
+			options.setErrorAction?.(action);
 			options.setErrorMessage(message);
 			options.setStep("error");
 			return {
@@ -15568,6 +15924,7 @@ async function submitWholeSeriesCheckout(options, deps, prepared, submitOptions)
 		claimToken: options.claimToken ?? void 0,
 		discountCode: options.discountCode.trim() || void 0,
 		collectionOptionKind: prepared.selectionSnapshot.collectionOptionKind,
+		checkoutAttemptId,
 		...urls
 	});
 	if (result.scope !== "wholeSeries") throw new Error("Unexpected registration scope for event checkout.");
@@ -16577,12 +16934,12 @@ function getEventRegistrationOverrideInput(props) {
 	if (!props.siteId) return {
 		ok: false,
 		reason: "missing-site-id",
-		message: "Event registration is missing site context."
+		message: "Online booking is unavailable right now. Please contact the organiser for help with booking."
 	};
 	if (!props.apiBaseUrl) return {
 		ok: false,
 		reason: "missing-api-base-url",
-		message: "Event registration is missing API configuration."
+		message: "Online booking is unavailable right now. Please contact the organiser for help with booking."
 	};
 	const content = props.content ?? {};
 	const data = isRecord(props.data) ? props.data : {};
@@ -16769,7 +17126,8 @@ function resolveHeadlessEventRegistrationStatus(wizard) {
 		} : { tag: "ready" };
 		case "error": return {
 			tag: "error",
-			message: wizard.errorMessage
+			message: wizard.errorMessage,
+			...wizard.errorAction ? { action: wizard.errorAction } : {}
 		};
 		case "select-event":
 		case "select-tickets":
@@ -16784,7 +17142,7 @@ function resolveHeadlessEventRegistrationView(wizard) {
 	};
 	if (!wizard.scopedEvents.some(isEventRegistrationAvailable) && !wizard.occurrenceContext) return {
 		kind: "unavailable",
-		message: "Registration is not currently available for this event."
+		message: "Booking is currently closed for this event. Please contact the organiser if you’d like to find out more."
 	};
 	switch (wizard.step) {
 		case "verifying-payment": return {
@@ -16802,7 +17160,7 @@ function resolveHeadlessEventRegistrationView(wizard) {
 		};
 		case "verifying-timeout": return {
 			kind: "verifying",
-			message: "Your registration is saved."
+			message: "Your booking is not confirmed yet. Please don’t make another booking while we check. You can check your payment status again in a moment."
 		};
 		case "select-event":
 		case "select-tickets":
@@ -17039,6 +17397,13 @@ function toWholeSeriesRegistrationEvents(offerings) {
 }
 //#endregion
 //#region ../blocks/src/system/runtime/nodes/event-registration/registrationWizardContext.ts
+function getEventSelectionDefaults(event) {
+	const suggestedAmount = getSlidingScaleForEvent(event)?.suggestedAmount;
+	return {
+		slidingAmountInput: suggestedAmount == null ? "" : formatCentsAsCurrencyInput(suggestedAmount),
+		attendanceMode: event.deliveryMode === "hybrid" ? null : event.deliveryMode ?? "in_person"
+	};
+}
 function parseCurrencyInputToCents(value) {
 	const trimmed = value.trim();
 	if (!trimmed) return null;
@@ -17086,7 +17451,7 @@ function resolveWaitlistClaimRestoration(input) {
 		const event = findEventByOccurrenceId(input.scopedEvents, subject.occurrenceId);
 		if (!event && input.occurrenceContextId !== subject.occurrenceId) return {
 			ok: false,
-			message: "This waitlist claim is for a different event."
+			message: "This waiting list invitation is for a different event. Please open the link in your invitation email."
 		};
 		return {
 			ok: true,
@@ -17103,7 +17468,7 @@ function resolveWaitlistClaimRestoration(input) {
 	const event = input.scopedEvents.find((candidate) => candidate.registrationSubject.kind === "wholeSeries" && candidate.registrationSubject.eventSeriesId === subject.eventSeriesId);
 	if (!event) return {
 		ok: false,
-		message: "This waitlist claim is for a different event run."
+		message: "This waiting list invitation is for a different event. Please open the link in your invitation email."
 	};
 	return {
 		ok: true,
@@ -17136,6 +17501,7 @@ function useWaitlistClaimRestoration(input) {
 			occurrenceContextId: input.occurrenceContextId
 		});
 		if (!restoration.ok) {
+			input.setters.setErrorAction?.("none");
 			input.setters.setErrorMessage(restoration.message);
 			input.setters.setStep("error");
 			return;
@@ -17214,6 +17580,8 @@ function useEventRegistrationWizardWithDeps(options, deps) {
 	});
 	const [registrationResult, setRegistrationResult] = useState(null);
 	const [errorMessage, setErrorMessage] = useState("");
+	const [errorAction, setErrorAction] = useState("retry");
+	const [optionsRefreshKey, setOptionsRefreshKey] = useState(0);
 	const [altchaSolution, setAltchaSolution] = useState(null);
 	const { authState: portalAuthState, profile: portalProfile } = deps.usePortalAuth();
 	const waitlistClaim = deps.useWaitlistClaim();
@@ -17243,10 +17611,8 @@ function useEventRegistrationWizardWithDeps(options, deps) {
 	const currentEvent = selectedEvent ?? preSelectedEvent;
 	const currentEventPricing = currentEvent ? resolveRuntimeEventPricing(currentEvent) : null;
 	const currentEventUsesTicketTypes = currentEventPricing !== null && publicEventPricingMode(currentEventPricing) === "ticket_types";
-	const selectedModeAvailability = selectedAttendanceMode ? (currentEvent?.attendanceModes ?? []).find((mode) => mode.mode === selectedAttendanceMode) ?? null : null;
-	const currentAvailableSpots = selectedModeAvailability?.availableSpots ?? currentEvent?.availableSpots;
-	const currentWaitlistEnabled = selectedModeAvailability?.waitlistEnabled ?? currentEvent?.waitlistEnabled ?? false;
-	const usesTicketTypeSelections = currentEventUsesTicketTypes && !(currentAvailableSpots === 0 && currentWaitlistEnabled === true);
+	const currentCanJoinWaitlist = currentEvent ? canJoinEventWaitlist(currentEvent, { attendanceMode: selectedAttendanceMode }) : false;
+	const usesTicketTypeSelections = currentEventUsesTicketTypes && !currentCanJoinWaitlist;
 	const eventTicketTypesForSelection = useMemo(() => getVisibleTicketTypes({
 		event: currentEvent,
 		eligibility: null,
@@ -17277,7 +17643,8 @@ function useEventRegistrationWizardWithDeps(options, deps) {
 		});
 	}, [flowState.ticketsCount, ticketsCount]);
 	const eligibilityResult = deps.useEligibility({
-		enabled: shouldLoadRegistrationOptions(portalAuthState, step),
+		refreshKey: optionsRefreshKey,
+		enabled: shouldRefreshAfterRegistrationError(step, errorAction, shouldLoadRegistrationOptions(portalAuthState, step)),
 		subject: registrationTarget?.subject ?? null,
 		attendanceMode: selectedAttendanceMode,
 		ticketSelections,
@@ -17306,6 +17673,7 @@ function useEventRegistrationWizardWithDeps(options, deps) {
 		});
 	}, [waitlistClaim.claim]);
 	const waitlistRestorationSetters = useMemo(() => ({
+		setErrorAction,
 		setErrorMessage,
 		setStep,
 		setSelectedEvent,
@@ -17329,6 +17697,7 @@ function useEventRegistrationWizardWithDeps(options, deps) {
 		if (waitlistClaim.requiresPortalLogin) return;
 		if (!waitlistClaim.error) return;
 		setErrorMessage(waitlistClaim.error);
+		setErrorAction("event");
 		setStep("error");
 	}, [
 		waitlistClaim.error,
@@ -17431,8 +17800,7 @@ function useEventRegistrationWizardWithDeps(options, deps) {
 		const event = currentEvent;
 		if (!event || publicEventPricingMode(resolveRuntimeEventPricing(event)) !== "ticket_types") return false;
 		if ((event.deliveryMode ?? "in_person") === "hybrid" && !selectedAttendanceMode) return false;
-		const selectedModeAvailability = selectedAttendanceMode ? (event.attendanceModes ?? []).find((mode) => mode.mode === selectedAttendanceMode) ?? null : null;
-		return !((selectedModeAvailability?.availableSpots ?? event.availableSpots) === 0 && (selectedModeAvailability?.waitlistEnabled ?? event.waitlistEnabled) === true);
+		return !canJoinEventWaitlist(event, { attendanceMode: selectedAttendanceMode });
 	}, [currentEvent, selectedAttendanceMode]);
 	const hasValidTicketSelection = !ticketTypeSelectionRequired || normalizedSelectedTicketLines.length > 0 && normalizedSelectedTicketLines.every((line) => {
 		if (!line.ticketTypeId) return false;
@@ -17513,6 +17881,7 @@ function useEventRegistrationWizardWithDeps(options, deps) {
 	]);
 	const handleDetailsComplete = async () => {
 		if (ticketTypeSelectionRequired && !hasValidTicketSelection) {
+			setErrorAction("places");
 			const message = "Choose at least one available ticket to continue.";
 			setErrorMessage(message);
 			setStep("error");
@@ -17523,6 +17892,7 @@ function useEventRegistrationWizardWithDeps(options, deps) {
 			};
 		}
 		if (slidingScaleSelectionMessage) {
+			setErrorAction("places");
 			setErrorMessage(slidingScaleSelectionMessage);
 			setStep("error");
 			return {
@@ -17540,7 +17910,8 @@ function useEventRegistrationWizardWithDeps(options, deps) {
 			};
 		}
 		if (waitlistClaim.claim === null && eligibility?.isFull && !eligibility.canJoinWaitlist) {
-			const message = "This event is sold out.";
+			const message = "Sorry, there aren’t enough places left for your selection. Please check the available places and choose again.";
+			setErrorAction("places");
 			setErrorMessage(message);
 			setStep("error");
 			return {
@@ -17656,6 +18027,7 @@ function useEventRegistrationWizardWithDeps(options, deps) {
 	const selectionMethod = paymentSelection.method;
 	const shouldShowDiscountToggle = discountContext !== null && discountUi.manualCodeEntryAllowed && (selectionMethod === "stripe" || selectionMethod === "pass_bundle" || selectionMethod === "membership_bundle");
 	const handleSubmit = deps.useEventRegistrationSubmit({
+		setErrorAction,
 		api,
 		registrationTarget,
 		selectedAttendanceMode,
@@ -17678,26 +18050,31 @@ function useEventRegistrationWizardWithDeps(options, deps) {
 			...current,
 			consentAccepted: false
 		}));
-		const slidingScale = getSlidingScaleForEvent(event);
-		setSelectedSlidingAmountInput(slidingScale?.suggestedAmount !== null && slidingScale?.suggestedAmount !== void 0 ? formatCentsAsCurrencyInput(slidingScale.suggestedAmount) : "");
-		setSelectedAttendanceMode((event.deliveryMode ?? "in_person") === "hybrid" ? null : (event.deliveryMode ?? "in_person") === "online" ? "online" : "in_person");
+		const defaults = getEventSelectionDefaults(event);
+		setSelectedSlidingAmountInput(defaults.slidingAmountInput);
+		setSelectedAttendanceMode(defaults.attendanceMode);
 		setSelectedTicketLines([]);
 		dispatchFlow({
 			type: "event-changed",
 			hasPreSelectedContext: true
 		});
 	};
-	const handleRetry = () => {
-		dispatchFlow({
-			type: "reset",
-			hasPreSelectedContext
-		});
-		setSelectedTicketLines([]);
-		setSelectedSlidingAmountInput("");
-		setSelectedAttendanceMode(preSelectedEvent?.deliveryMode === "online" ? "online" : preSelectedEvent?.deliveryMode === "in_person" ? "in_person" : null);
-		setErrorMessage("");
-		setPendingRegistrationReference(null);
-	};
+	const handleRetry = () => recoverRegistrationError(resolveRegistrationRecoveryAction(step, errorAction), {
+		canJoinWaitlist: canRecoverToWaitlist(eligibility),
+		refreshOptions: () => setOptionsRefreshKey((value) => value + 1),
+		clearError: () => setErrorMessage(""),
+		setStep,
+		reset: () => resetRegistrationAfterExpiry({
+			hasPreSelectedContext,
+			preSelectedEvent,
+			dispatchFlow,
+			setSelectedTicketLines,
+			setSelectedSlidingAmountInput,
+			setSelectedAttendanceMode,
+			setErrorMessage,
+			setPendingRegistrationReference
+		})
+	});
 	const handlePaymentStepStateChange = useCallback((state) => {
 		setPaymentStepState(state);
 	}, []);
@@ -17760,6 +18137,7 @@ function useEventRegistrationWizardWithDeps(options, deps) {
 		handleGuestShakeEnd,
 		registrationResult,
 		errorMessage,
+		errorAction,
 		altchaSolution,
 		setAltchaSolution,
 		portalAuthState,