@v-office/website-headless 1.4.1 → 1.5.0

package/README.md

@@ -1457,8 +1457,8 @@ serializable, so it stays in this store until then.
 | `caps`               | none            | `{ maxGuests?, petsAllowed? }` from the catalogue, until `loadGuestCaps()` adds availability's                              |
 | `onEvent`            | none            | receives every `CheckoutEventDetail`; without it a rate fault is logged with `console.warn`                                 |
 
-`start()` parks the context and prices the handed-over stay (idempotent); `dispose()` drops every
-in-flight result.
+`start()` parks the context, recognizes a stay this tab already booked (`earlierBooking`) and prices
+the handed-over stay (idempotent); `dispose()` drops every in-flight result.
 
 `CheckoutPhase` (`state.phase.kind`): `loading`, `missing-stay` (no complete stay arrived), `ready`,
 `unavailable` (`reason`), `error` (`retry()`), `booked` (`confirmation` is set).
@@ -1468,6 +1468,7 @@ refused while `blockers` is not empty.
 
 | blocker               | meaning                                                    |
 | --------------------- | ---------------------------------------------------------- |
+| `earlier-booking`     | this tab already booked the rental for these dates         |
 | `no-quote`            | no priced quote, or the phase is not `ready`               |
 | `price-pending`       | the shown price does not belong to the shown stay yet      |
 | `busy`                | a selection or a re-quote is running                       |
@@ -1482,7 +1483,13 @@ extra plus `count`, `canAdd`, `canRemove`), `policy` (`CheckoutPolicyState`: `ap
 `noneLabel`, `chosen`, `documents`, `requiredDocuments`, `documentsPending`), `voucher`
 (`CheckoutVoucherState`: `applied`, `error`, `checking`), `consents`, `pricePending`, `busy`,
 `issue` (`CheckoutIssue`: `reason`, `retryable`), `selectionError`, `submit`
-(`"idle" | "submitting" | "failed"`), `confirmation`, `payment` (`busyOption`, `failed`).
+(`"idle" | "submitting" | "failed"`), `confirmation`, `earlierBooking`, `payment` (`busyOption`,
+`failed`).
+
+`earlierBooking` is the `BookingSnapshot` of the booking this tab already made for this rental and
+these dates (a reload of the booked checkout, the browser's back button), read on `start()` from the
+payment-return snapshot; null otherwise. A UI renders it in place of the order (its `bookingNumber`
+and `kind`; no payment entries, the confirmation e-mail has them). Other dates are not that booking.
 
 | action                                                               | what it does                                                                                        |
 | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
@@ -1573,8 +1580,9 @@ The checkout flow calls these; a custom checkout built without the flow calls th
 - `submitBooking(sdk, quote, contact, options)` → `BookingConfirmation` (`kind`, `bookingNumber`,
   `schedules`, `alternatives` (settle the whole balance at once: an alternative, never added),
   `insurancePayments`, `payable`). ⚠ Reserves for real. `SubmitBookingOptions`: `returnPath`,
-  `kind`, `bankHolderFallback`, `stay`. Writes the payment-return snapshot the moment the booking
-  number exists. Logs the SDK's cause and rethrows.
+  `kind`, `bankHolderFallback`, `stay`, `rentalId` (a reloaded checkout recognizes the booking by
+  it). Writes the payment-return snapshot the moment the booking number exists. Logs the SDK's cause
+  and rethrows.
 - `PaymentScheduleView`: `kind`, `label`, `dueOn` (a complete sentence: render, never parse),
   `paymentAt`, `lines` (`PaymentLine`), `amount`, `options` (empty = informational).
 - `isSubmittableOption(option)`: every kind but `bank_transfer`.
@@ -1601,14 +1609,16 @@ the guest's declaration).
 ### Payment return
 
 The return URL cannot carry the booking number, so a snapshot this tab wrote (sessionStorage, only
-what the page renders, no personal data) is what the return page shows.
+what the page renders and the rental id, no personal data) is what the return page shows, and what
+the checkout recognizes a booked stay by (`earlierBooking`).
 
 - `readPaymentReturn(search, storage?)` → `PaymentReturn`, by `state`: `"booked"` (this tab booked:
   `snapshot` and `paymentCancelled`), `"returned"` (a provider return without a snapshot:
   `paymentCancelled`), or `"none"` (a bare or tracking-only URL). `paymentCancelled` is the
   provider's cancel marker (`payment=stripe&cancel=true`).
-- `BookingSnapshot`: `bookingNumber`, `kind`, `rentalName?`, `location?`, `href?`, `images?`
-  (`SnapshotImage`, at most five), `start?`, `end?`, `guests?`, `total?`.
+- `BookingSnapshot`: `bookingNumber`, `kind`, `rentalId?` (since 1.5.0), `rentalName?`,
+  `location?`, `href?`, `images?` (`SnapshotImage`, at most five), `start?`, `end?`, `guests?`,
+  `total?`.
 - `saveCheckoutContext(context, storage?)`: the flow calls it on `start()`. Never throws.
 - `CHECKOUT_CONTEXT_KEY`, `BOOKING_SNAPSHOT_KEY`: the sessionStorage keys.
 

package/dist/index.d.mts

@@ -1831,6 +1831,9 @@ interface SubmitBookingOptions {
   bankHolderFallback?: string | undefined;
   /** The stay being booked, for the payment-return snapshot. */
   stay: Stay;
+  /** The rental being booked, for the payment-return snapshot: a reload of the checkout recognizes
+   *  the booking by it (`CheckoutState.earlierBooking`). */
+  rentalId?: string | undefined;
 }
 /** ⚠ USER-initiated only: reserves for real. `quote` must be the live instance with every selection
  *  applied. Logs the SDK's cause and rethrows (nothing is necessarily booked when it throws). Writes
@@ -1964,6 +1967,9 @@ interface BookingSnapshot {
   bookingNumber: string;
   /** A booking or an option. */
   kind: BookingKind;
+  /** The booked rental's PMS id: a reload of the checkout recognizes its booking by it. Absent in a
+   *  snapshot written before 1.5.0. */
+  rentalId?: string;
   /** The booked rental's name. */
   rentalName?: string;
   /** The rental's location line. */
@@ -2093,7 +2099,7 @@ type CheckoutPhase = {
   kind: "booked";
 };
 /** One reason the order button is off, in the order the UI should mention them. */
-type CheckoutBlocker = "no-quote" | "price-pending" | "busy" | "issue" | "child-ages" | "insurance-documents" | "consents";
+type CheckoutBlocker = "earlier-booking" | "no-quote" | "price-pending" | "busy" | "issue" | "child-ages" | "insurance-documents" | "consents";
 /** One extra as the UI renders it. */
 interface CheckoutService extends QuoteAddonService {
   /** Units chosen (0 = not booked). */
@@ -2187,6 +2193,11 @@ interface CheckoutState {
   submit: "idle" | "submitting" | "failed";
   /** The confirmation after `book()`, or null. */
   confirmation: BookingConfirmation | null;
+  /** The booking this tab already made for this rental and these dates, after a reload of the booked
+   *  checkout or a way back to it (the return page's snapshot, read on `start()`; only the tab's last
+   *  booking is kept). While it is set the order is refused (`earlier-booking`); other dates are not
+   *  it. The snapshot keeps no payment entries: the confirmation e-mail has them. Null otherwise. */
+  earlierBooking: BookingSnapshot | null;
   /** The payment buttons' state: the option redirecting now, and a failed start. */
   payment: {
     busyOption: SubmittableBookingPaymentOption | null;
@@ -2231,7 +2242,8 @@ interface CheckoutActions {
 }
 /** The checkout store: its state, its actions and its lifecycle. */
 interface CheckoutFlow extends Store<CheckoutState>, CheckoutActions {
-  /** Park the context and price the handed-over stay. Idempotent. */
+  /** Park the context, recognize a stay this tab already booked (`earlierBooking`) and price the
+   *  handed-over stay. Idempotent. */
   start(): void;
   /** Cancel pending work and drop every in-flight result. */
   dispose(): void;

package/dist/index.mjs

@@ -7043,9 +7043,11 @@ function snapshotOf(record) {
 	const end = record["end"];
 	const guests = guestsOf(record["guests"]);
 	const total = text(record["total"]);
+	const rentalId = text(record["rentalId"]);
 	return {
 		bookingNumber,
 		kind: record["kind"] === "option" ? "option" : "booking",
+		...rentalId ? { rentalId } : {},
 		...rentalFields(record),
 		...isIsoDay(start) ? { start } : {},
 		...isIsoDay(end) ? { end } : {},
@@ -7066,12 +7068,13 @@ function classifyReturn(params, storage) {
 		paymentCancelled
 	} : { state: "none" };
 }
-function writeSnapshot({ bookingNumber, kind, stay, total }, storage) {
+function writeSnapshot({ bookingNumber, kind, rentalId, stay, total }, storage) {
 	const context = readJson(CHECKOUT_CONTEXT_KEY, storage);
 	const { adults, children, babies, pets } = stay.party;
 	const snapshot = {
 		bookingNumber,
 		kind,
+		...rentalId ? { rentalId } : {},
 		...context ? rentalFields(context) : {},
 		start: stay.start,
 		end: stay.end,
@@ -7095,6 +7098,8 @@ const readPaymentReturn = (search, storage) => classifyReturn(new URLSearchParam
 const writeBookingSnapshot = (booking, storage) => {
 	writeSnapshot(booking, resolveStorage(storage));
 };
+/** See {@link ReadBookingSnapshot}. */
+const readBookingSnapshot = (storage) => snapshotOf(readJson(BOOKING_SNAPSHOT_KEY, resolveStorage(storage)));
 //#endregion
 //#region src/checkout/booking.ts
 async function book(sdk, quote, contact, options) {
@@ -7111,6 +7116,7 @@ async function book(sdk, quote, contact, options) {
 	writeBookingSnapshot({
 		bookingNumber: out.bookingNumber,
 		kind,
+		rentalId: options.rentalId,
 		stay: options.stay,
 		total: quote.bookingCardInformation.total
 	});
@@ -7521,13 +7527,20 @@ function insuranceOf(raw) {
 		documentsPending: insuranceDocsPending(chosen ?? void 0, raw.insuranceDocs)
 	};
 }
-function derive(raw, holds, kind, how, availability) {
+/** The rental's last booking in this tab is this stay's when its dates are; the party does not count
+*  (the rental is taken for those nights whoever comes). */
+function earlierBookingOf(earlier, stay) {
+	return earlier && stay && earlier.start === stay.start && earlier.end === stay.end ? earlier : null;
+}
+function derive(raw, holds, kind, how, availability, earlier) {
 	const busy = holds > 0;
 	const stayKey = raw.stay ? stayKeyOf(raw.stay) : null;
 	const quotedKey = raw.quoted ? stayKeyOf(raw.quoted) : null;
 	const pricePending = stayKey !== null && stayKey !== quotedKey && raw.issue?.key !== stayKey;
 	const insurance = insuranceOf(raw);
+	const earlierBooking = earlierBookingOf(earlier, raw.stay);
 	const blockers = [];
+	if (earlierBooking) blockers.push("earlier-booking");
 	if (!raw.view || raw.phase.kind !== "ready") blockers.push("no-quote");
 	if (pricePending) blockers.push("price-pending");
 	if (busy) blockers.push("busy");
@@ -7556,6 +7569,7 @@ function derive(raw, holds, kind, how, availability) {
 		blockers,
 		submit: raw.submit,
 		confirmation: raw.confirmation,
+		earlierBooking,
 		payment: raw.payment
 	};
 }
@@ -7581,11 +7595,14 @@ function checkoutFlow(source, options) {
 	let sdk = null;
 	let availability = null;
 	let capsRequested = false;
+	/** This rental's booking from the tab's return snapshot, read on `start()`. */
+	let earlier = null;
 	const faultsReported = /* @__PURE__ */ new Set();
 	const lineOrder = /* @__PURE__ */ new Map();
-	const store = createStore(derive(raw, holds, handover.kind, how, availability));
+	const derived = () => derive(raw, holds, handover.kind, how, availability, earlier);
+	const store = createStore(derived());
 	const publish = () => {
-		if (!disposed) store.setState(derive(raw, holds, handover.kind, how, availability));
+		if (!disposed) store.setState(derived());
 	};
 	const patch = (next) => {
 		raw = {
@@ -7748,7 +7765,8 @@ function checkoutFlow(source, options) {
 				returnPath: options.returnPath,
 				kind: handover.kind,
 				bankHolderFallback: options.bankHolderFallback,
-				stay
+				stay,
+				rentalId
 			});
 			patch({
 				confirmation,
@@ -7972,6 +7990,9 @@ function checkoutFlow(source, options) {
 			if (started || disposed) return;
 			started = true;
 			if (options.context) saveCheckoutContext(options.context);
+			const snapshot = readBookingSnapshot();
+			earlier = snapshot?.rentalId === rentalId ? snapshot : null;
+			if (earlier) publish();
 			schedule(0);
 		},
 		dispose() {

package/instructions/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 Release notes of `@v-office/website-headless`, newest first. Each version has its own directory.
 
+- `versions/1.5.0/CHANGELOG.md`: release notes for 1.5.0
 - `versions/1.4.1/CHANGELOG.md`: release notes for 1.4.1
 - `versions/1.4.0/CHANGELOG.md`: release notes for 1.4.0
 - `versions/1.3.0/CHANGELOG.md`: release notes for 1.3.0

package/instructions/MIGRATION.md

@@ -4,6 +4,7 @@
 
 Migration guides of `@v-office/website-headless`, newest first. Apply them in order when skipping versions.
 
+- `versions/1.5.0/MIGRATION.md`: Migration: 1.4.1 to 1.5.0
 - `versions/1.4.1/MIGRATION.md`: Migration: 1.4.0 to 1.4.1
 - `versions/1.4.0/MIGRATION.md`: Migration: 1.3.0 to 1.4.0
 - `versions/1.3.0/MIGRATION.md`: Migration: 1.2.0 to 1.3.0

package/instructions/versions/1.5.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog: 1.5.0
+
+The checkout recognizes a stay the guest already booked in this browser tab. After `book()` the
+checkout page's URL still describes the stay, so a reload, or the browser's back button (from the
+payment provider's page, say), started a new checkout for it: the guest saw the PMS refuse the
+dates they had just booked, or, while the PMS's availability had not caught up, was offered the
+order a second time. The checkout now names that booking and does not order the stay again.
+
+## Added
+
+- `CheckoutState.earlierBooking`: the booking this tab already made for this rental and these
+  dates, as a `BookingSnapshot` (`bookingNumber`, `kind`, `start`, `end`, `guests`, `total`), or
+  null. The flow reads it on `start()` from the payment-return snapshot `book()` writes to session
+  storage, so only the tab's last booking counts, and only while the tab lives.
+- `BookingSnapshot.rentalId` and `SubmitBookingOptions.rentalId`: the rental a snapshot belongs to.
+  The checkout flow passes it. A site that calls `submitBooking` itself passes its rental id to get
+  the same recognition.
+
+## Fixed
+
+- A checkout started for a stay this tab already booked refuses the order: `blockers` starts with
+  `"earlier-booking"` and `book()` does nothing, whatever the quote says.
+
+## Unchanged
+
+- The stay is still priced. A checkout UI that does not render `earlierBooking` shows what it
+  showed before (usually the PMS refusing the dates), and the blocker keeps its order button off.
+- Other dates are not that booking: after `setDates` to another range `earlierBooking` is null and
+  the checkout orders as usual; back on the booked dates it is set again. The party does not count,
+  because the rental is taken for those nights.
+- A snapshot written before 1.5.0 has no rental id and is no earlier booking.
+- `readPaymentReturn` and the return page read the snapshot as before.

package/instructions/versions/1.5.0/MIGRATION.md

@@ -0,0 +1,37 @@
+# Migration: 1.4.1 to 1.5.0
+
+No changes required. A site with the platform's `Booking` shows the earlier booking through
+`@v-office/website-components` 1.2.0. A site with its own checkout keeps working: for a stay the
+tab already booked its order button stays off (`blockers` holds `"earlier-booking"`), and it shows
+what it showed before.
+
+## Showing the earlier booking in a site's own checkout
+
+A site that renders its own checkout (over `useCheckoutFlow` or `createCheckoutFlow`) can show the
+booking instead. Render `state.earlierBooking` in place of the order: the guest booked this stay and
+needs its booking number, not a refusal of the dates or a second order form.
+
+```tsx
+const { state } = useCheckoutFlow({ … });
+if (state.earlierBooking) {
+  const { bookingNumber, kind } = state.earlierBooking;
+  return (
+    <section role="status">
+      <h2>{kind === "option" ? "Die Reservierung ist eingegangen." : "Die Buchung ist eingegangen."}</h2>
+      <p>Buchungsnummer: {bookingNumber}. Die Bestätigung mit allen Details folgt per E-Mail.</p>
+    </section>
+  );
+}
+```
+
+- Use the site's own confirmation wording; `kind` tells a booking from an option.
+- The snapshot keeps no payment entries (no bank details, no payment buttons): point the guest to
+  the confirmation e-mail.
+- A checkout with a date editor may keep it beside the notice: other dates are not that booking.
+- If a site's checkout states why its order button is off, `"earlier-booking"` is the first reason.
+
+## 1. Upgrade
+
+```sh
+pnpm add --save-exact @v-office/website-headless@1.5.0
+```

package/instructions/versions/1.5.0/release.json

@@ -0,0 +1,3 @@
+{
+  "componentsAffectedByHeadlessChange": ["booking"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v-office/website-headless",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Framework-free behaviour layer for v-office websites, never UI: stores, pure rules and SDK runners for the search bar, results, map, showcase, quote, checkout and contact form, the rental and card models, and progressive-enhancement engines for server-rendered markup (./enhance)",
   "license": "UNLICENSED",
   "repository": {
@@ -26,7 +26,7 @@
   },
   "devDependencies": {
     "@types/node": "26.5.1",
-    "@v-office/website-sdk": "3.0.0",
+    "@v-office/website-sdk": "3.2.0",
     "effect": "4.0.0-rc.115",
     "jsdom": "^30.0.1",
     "oxfmt": "0.67.0",