@v-office/website-headless 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,912 @@
+import { BookingPaymentOption, BookingPaymentScheduleKind, GuestQuote, GuestQuoteResult, SubmittableBookingPaymentOption, createWebsiteSDK } from "@v-office/website-sdk";
+//#region src/store/index.d.ts
+/**
+ * The smallest external store that every UI framework can subscribe to:
+ * `getState` + `subscribe` is what React's useSyncExternalStore, Vue's
+ * watchers, Svelte's store contract and a plain `<script>` all understand.
+ * Flows in this package (checkout today, more later) build on it so the
+ * package never depends on a framework; the adapters live in ./react and
+ * friends.
+ */
+type Listener<S> = (state: S) => void;
+type Unsubscribe = () => void;
+interface Store<S> {
+  getState(): S;
+  subscribe(listener: Listener<S>): Unsubscribe;
+}
+interface WritableStore<S> extends Store<S> {
+  /** Replaces the state and notifies every listener. Same reference = no-op. */
+  setState(next: S): void;
+}
+declare function createStore<S>(initial: S): WritableStore<S>;
+//#endregion
+//#region src/sdk.d.ts
+type WebsiteSdk = ReturnType<typeof createWebsiteSDK>;
+/**
+ * Render `error` and its whole cause chain as indented JSON.
+ *
+ * Walks the chain because a cause nests (a `CoreSDKError` wrapping a thrown
+ * transport object wrapping a response body). Skips `stack` — a backend
+ * refusal is not diagnosed from the frames that asked, and the raw error is
+ * one `console.error` away for the cases that are. Reads `name`/`message` by
+ * hand because `Error` declares both non-enumerable, so `Object.entries`
+ * alone would return an Error as `{}`.
+ *
+ * **`cause` is read by hand for exactly the same reason**, and it was missed
+ * the first time — so this file shipped without the one property it exists to
+ * print. Verified against the real class: `Object.keys(new CoreSDKError({…}))`
+ * is `["source", "operation", "_tag"]`, and `cause`'s own descriptor carries
+ * `enumerable: false`. `Object.entries` therefore never saw it, and every
+ * `CoreSDKError` logged as the five bland fields above with the sentence that
+ * names the fault dropped.
+ */
+declare function describeSdkError(error: unknown): string;
+/**
+ * Log a failed SDK call with the backend's reason, tagged by `scope`.
+ *
+ * `scope` names the SDK operation, not the component — `"quote.selectInsurance"`
+ * rather than `"the extras panel"`. What the console needs to answer is which
+ * call the backend refused; which button was on screen at the time is the part
+ * the reporter already knows.
+ *
+ * Logs the description ALONE. Callers that also have the raw error in hand may
+ * log it separately for a clickable stack; doubling it here would print every
+ * failure twice on the surfaces that already do.
+ */
+declare function logSdkFailure(scope: string, error: unknown): void;
+//#endregion
+//#region src/quote.d.ts
+/** One row of the price breakdown. `label`/`amount` are the SDK's own
+ *  `position`/`appliedCharge`, verbatim; `nested` marks a sub-line so the UI
+ *  can indent it under the line above.
+ *
+ *  `discount` marks a row synthesised from an SDK price MODIFIER rather than
+ *  from a charge line — see `adaptGuestQuote` for why those rows exist. Its
+ *  `amount` is the modifier's own signed string ("-140,00 €"), so the row is a
+ *  deduction from the running total, not another charge. */
+interface QuoteLine {
+  label: string;
+  amount: string;
+  nested: boolean;
+  discount: boolean;
+}
+interface PriceQuote {
+  /** Section/line breakdown flattened in SDK order (sub-items follow their
+   *  parent line, flagged `nested`). */
+  lines: QuoteLine[];
+  /** SDK `bookingCardInformation.total`, verbatim (already locale-formatted). */
+  total: string;
+}
+/** Bookable add-on from `quote.additionalServices`, verbatim fields. */
+interface QuoteAddonService {
+  id: string;
+  label: string;
+  /** SDK charge string as-is (e.g. "25,00 €" — the PMS's own formatting). */
+  charge: string;
+  description?: string | undefined;
+  /** Max selectable per booking; absent = the SDK states no cap. */
+  maxPerBooking?: number | undefined;
+  /** Quantity the PMS PROPOSES for this service (`0` included). A proposal,
+   *  NOT a selection — the distinction is the whole reason this field is
+   *  named the way it is.
+   *
+   *  THE SDK IS EXPLICIT (`instructions/quote.md`): "When the backend provides
+   *  a line amount for an optional service, it is exposed as `proposedQuantity`
+   *  (including `0`). By default this is informational only and is not added to
+   *  the quote." A fresh quote carries these as selections ONLY on a project
+   *  that sets `shouldAddProposedAdditionalServiceAmount: true`, which the SDK
+   *  defaults to `false`.
+   *
+   *  SO THIS IS NEVER A BASELINE. What a quote actually has selected is not
+   *  readable from the public SDK surface at all — `GuestQuote` keeps its
+   *  `selections` behind an unexported symbol, and there is no quote-side
+   *  counterpart to `getBookingModificationSelectedQuantity`. Code that needs a
+   *  known starting point therefore MAKES one with `clearQuoteServices` and
+   *  steps up from zero. It does not read this number and hope.
+   *
+   *  RENAMED FROM `preSelectedQuantity` IN booking-kit 1.21.0, because the old
+   *  name stated the one thing the value does not mean, and `checkout-kit`
+   *  believed it — see that kit's 1.21.0 entry. */
+  proposedQuantity: number;
+  /** False only when the PMS explicitly marks this service unbookable for the
+   *  current multi-rate combination (SDK `available: false`). Absent → true.
+   *  The UI disables adding it rather than letting the click silently no-op. */
+  available: boolean;
+  /** PMS's own reason the service is unavailable, verbatim; self-hides when
+   *  the feed omits it. */
+  unavailableReason?: string | undefined;
+}
+interface QuotePolicyRule {
+  daysBeforeArrival: number;
+  /** SDK's formatted percentage string, verbatim. */
+  refundPercentage: string;
+}
+/** Selectable cancellation policy from `quote.cancellationPolicies`. */
+interface QuoteCancellationPolicy {
+  id: string;
+  label: string;
+  selected: boolean;
+  description?: string | undefined;
+  markUpPercentage?: string | undefined;
+  processingFee?: string | undefined;
+  rules: QuotePolicyRule[];
+  /** False only when the PMS explicitly marks this policy unselectable for the
+   *  current multi-rate combination (SDK `available: false`). Absent → true. */
+  available: boolean;
+  /** PMS's own reason the policy is unavailable, verbatim; self-hides when
+   *  the feed omits it. */
+  unavailableReason?: string | undefined;
+}
+/** Voucher status echoed back on a re-priced quote (`quote.voucher`). On v10
+ *  the SDK authoritatively reports whether the code applied a modifier; v9
+ *  reports `"unknown"`. `message` is the PMS's own note, verbatim. */
+interface QuoteVoucher {
+  code: string;
+  status: "applied" | "not_applied" | "unknown";
+  message?: string | undefined;
+}
+/** One selectable travel-insurance product from `quote.insurance.options`
+ *  (kind "insurance"), verbatim fields. The backend loads these live from
+ *  whichever insurer the hub setup configures, and only when that setup enables
+ *  insurance at all — otherwise the SDK returns the "none" option alone and the
+ *  adapter yields no `QuoteInsurance`. */
+interface QuoteInsuranceOption {
+  id: string;
+  label: string;
+  /** SDK's own locale-formatted premium (e.g. "14,00 €"). There is no numeric
+   *  amount on the public shape — the SDK keeps that internally — so a premium
+   *  can be DISPLAYED but never added to another price. */
+  formattedPrice: string;
+  description?: string | undefined;
+  /** Insurer logo, when the feed provides one. The kit's insurance card does
+   *  not render it; a site that wants the insurer's mark has it here. */
+  logoUrl?: string | undefined;
+  /** Plan feature names, verbatim (e.g. "Reiserücktritt"). */
+  features?: string[] | undefined;
+  /** Product documents (IPID, Bedingungen, …) — label + URL, verbatim. */
+  resources?: {
+    label: string;
+    url: string;
+  }[] | undefined;
+  /** True when the product needs per-traveler data before selection (the ERGO
+   *  path: traveler forms, pre-contract, SEPA mandate, a post-booking
+   *  `bookInsurance` call). False = the id alone completes the selection and
+   *  the premium books WITH the rental, because `booking.book` injects
+   *  `travelInsurancePlan`/`travelInsuranceAmount` from the quote for exactly
+   *  these products. The checkout only offers the ones it can complete. */
+  requiresTravelers: boolean;
+}
+/** Travel-insurance choice on a live quote (`quote.insurance`), flattened for
+ *  the checkout's radio section. Absent from the view when the feed offers no
+ *  real product (options empty or "none"-only) — the section self-hides.
+ *
+ *  The premium is NOT part of `card.total`: the SDK prices the stay and the
+ *  policy separately, so a UI that shows both must show them as two figures.
+ *  Adding them would mean parsing the PMS's formatted strings, which this file
+ *  does not do for any other charge either. */
+interface QuoteInsurance {
+  /** The SDK's own "no insurance" label, verbatim. */
+  noneLabel: string;
+  options: QuoteInsuranceOption[];
+  /** Selected product id, or null = no insurance (the default). */
+  selectedId: string | null;
+}
+/** The renderable view of a live GuestQuote — card + selectable options. */
+interface QuoteView {
+  card: PriceQuote;
+  services: QuoteAddonService[];
+  policies: QuoteCancellationPolicy[];
+  /** Present once a code has been submitted and the quote re-priced; absent on
+   *  a fresh quote. */
+  voucher?: QuoteVoucher | undefined;
+  /** Selectable travel insurance — absent when the feed offers no product. */
+  insurance?: QuoteInsurance | undefined;
+}
+type QuoteResult = {
+  status: "available";
+  /** Flattened price card (back-compat: the widget renders this). */
+  quote: PriceQuote;
+  /** The live SDK quote instance — required by booking.book. In-memory
+   *  only; not serializable across navigations. */
+  live: GuestQuote;
+  /** Add-ons + policies for the checkout's optional sections. */
+  view: QuoteView;
+} | {
+  status: "unavailable";
+  reason: string;
+  code: QuoteUnavailableCode;
+};
+/** Why the SDK refused to price the stay — machine-readable since website-sdk
+ *  2.16.0, and the ONLY thing callers may branch on. `reason` is localized and
+ *  carries the SAME text for different codes, so comparing it is how a UI ends
+ *  up telling a guest a free week is booked out.
+ *
+ *  DERIVED from `GuestQuoteResult`, not re-listed: the SDK owns this set and a
+ *  copy here would rot silently the day it grows a fourth member.
+ *  `@v-office/sdk-core` exports the union as `GuestQuoteUnavailableCode`, but
+ *  `@v-office/website-sdk` does not re-export it and sdk-core is a transitive
+ *  dependency an adopting project does not declare — so `Extract` off the
+ *  result type is the reachable spelling. */
+type QuoteUnavailableCode = Extract<GuestQuoteResult, {
+  status: "unavailable";
+}>["code"];
+/** The two codes that mean "the stay WAS priced, but the rental's rate setup
+ *  cannot be resolved to the single multi-rate a booking must be written
+ *  against" — a v10 backend-configuration fault the guest has no part in.
+ *
+ *  `resolveV10MultiRate` matches the priced quote's service lines against the
+ *  rental's multi-rate rows for the policy, then tie-breaks on `baseRentRate`,
+ *  which only fires when EXACTLY ONE tied row carries it. A rental whose PMS
+ *  holds several equivalent base-rent rows per cancellation policy leaves the
+ *  tie unbroken, and the SDK reports the quote unavailable rather than guess a
+ *  rate — the price alone does not identify which row the booking belongs to.
+ *
+ *  There is nothing an adopting site can do about the stay itself: it stays
+ *  unbookable until the surplus rows are removed in the PMS. What the site owes
+ *  the guest is honest copy — never the generic "not available", which asserts
+ *  a booking conflict that does not exist. */
+declare const MULTI_RATE_CODES: readonly ["AmbiguousMultiRate", "UnresolvableMultiRate"];
+/** True when an unavailable quote is a rate-configuration fault rather than a
+ *  genuinely unbookable stay. Callers branch the MESSAGE on this and must keep
+ *  booking disabled either way (SDK 2.16.0 MIGRATION, "Required Consumer
+ *  Work"). */
+declare function isRateConfigurationFault(code: QuoteUnavailableCode | undefined): boolean;
+interface QuoteOccupancy {
+  adults: number;
+  children: number;
+  childrenAges?: number[] | undefined;
+  babies: number;
+  pets: number;
+}
+/** Flatten a GuestQuote into the renderable view. Values verbatim.
+ *
+ * DISCOUNTS: the SDK does not hand us a discount LINE. When the PMS applies a
+ * price modifier (Frühbucher/Last-Minute, a voucher, a policy markup) it hangs
+ * it off the charge line as `modifiers[]` — label plus signed amount — and puts
+ * the pre-modifier figure in `totalBeforeModifiers`, leaving `appliedCharge`
+ * already net. Render `appliedCharge` alone (what every adoption did until now)
+ * and the saving is invisible: the guest sees only the reduced number and is
+ * never told a discount applied.
+ *
+ * So each modifier becomes its own row, and the line above it switches to
+ * `totalBeforeModifiers`. That pairing is not cosmetic — it is what makes the
+ * card add up. A deduction row under an `appliedCharge` that has ALREADY been
+ * reduced double-counts on sight: the column no longer sums to the total, and a
+ * guest checking the arithmetic finds it wrong. Gross line, then the deduction,
+ * then the remaining charges: 1.694,00 − 140,00 + 42,70 = 1.596,70.
+ *
+ * `bookingCardInformation.totalBeforeModifiers` is deliberately NOT rendered.
+ * The deduction rows already carry the saving, and a struck-through "was" price
+ * would state it a second time — as the one figure on the card that cannot be
+ * checked by adding, and as a price claim the customer would have to stand
+ * behind. The total stays the single net number.
+ */
+declare function adaptGuestQuote(quote: GuestQuote): QuoteView;
+/** Price a stay for `rentalId`. The caller owns the SDK instance and its
+ *  lifecycle — pass a shared one to reuse its queue + cache across the caller's
+ *  lifetime. `voucher` re-prices with a code (the PMS decides what it's worth). */
+declare function fetchQuote(rentalId: string, period: {
+  start: string;
+  end: string;
+}, occupancy: QuoteOccupancy, sdk: WebsiteSdk, voucher?: string): Promise<QuoteResult>;
+type QuoteSelectionResult = {
+  ok: true;
+  quote: GuestQuote;
+} | {
+  ok: false;
+  reason?: string | undefined;
+};
+declare function addQuoteService(quote: GuestQuote, id: string, sdk: WebsiteSdk): Promise<QuoteSelectionResult>;
+declare function removeQuoteService(quote: GuestQuote, id: string, sdk: WebsiteSdk): Promise<QuoteSelectionResult>;
+/** Drop every additional-service selection from `quote`.
+ *
+ *  A fresh quote's selection state is not knowable from the service list. It is
+ *  empty by default and carries the PMS's proposed quantities only when the
+ *  project sets `shouldAddProposedAdditionalServiceAmount: true` — an SDK
+ *  option a component cannot see — and the quote will not say which happened
+ *  (`GuestQuote.selections` is behind an unexported symbol). Rather than branch
+ *  on something invisible, a caller that needs a known starting point clears
+ *  first and steps up from zero with `addQuoteService`. */
+declare function clearQuoteServices(quote: GuestQuote, sdk: WebsiteSdk): Promise<QuoteSelectionResult>;
+declare function selectQuotePolicy(quote: GuestQuote, id: string, sdk: WebsiteSdk): Promise<QuoteSelectionResult>;
+/** Select a travel-insurance product (`id`) or none (`null`). Unlike the
+ *  service/policy calls the SDK returns the new GuestQuote directly and throws
+ *  on failure (unknown id) — normalized here to the same QuoteSelectionResult
+ *  the other selection helpers use, so a stale id is a silent no-op the caller
+ *  handles by keeping the previous quote.
+ *
+ *  For a product that needs no traveler data this is the COMPLETE selection:
+ *  the premium books with the rental via `booking.book`, which reads the plan
+ *  off the quote. A product with `requiresTravelers` needs the pre-contract /
+ *  payment / `bookInsurance` steps on top, which the checkout does not
+ *  implement — it offers only the products it can complete. */
+declare function selectQuoteInsurance(quote: GuestQuote, id: string | null, sdk: WebsiteSdk): Promise<QuoteSelectionResult>;
+/**
+ * The concrete "free cancellation until" date for ONE policy — DERIVED, not
+ * fabricated: the PMS states its rules relatively (`daysBeforeArrival` +
+ * `refundPercentage`), so with the chosen arrival in hand the deadline is
+ * plain arithmetic (arrival − daysBeforeArrival), the same category of
+ * derivation as computing nights from a range.
+ *
+ * Uses the policy's full-refund (100%) rule. Returns null when the policy has
+ * no full-refund rule OR the derived date is already in the past (booking
+ * inside the window — advertising a bygone deadline would be wrong).
+ */
+/** The policy's full-refund rule, if it has one. The refund figure is the SDK's
+ *  own formatted string ("100%"), so this reads it rather than comparing a
+ *  number — the one place that pattern is written, because both the derived
+ *  deadline and the "is this a refundable rate at all" question depend on it. */
+declare function fullRefundRule(policy: QuoteCancellationPolicy | undefined): QuotePolicyRule | undefined;
+declare function policyFreeCancellationUntil(policy: QuoteCancellationPolicy | undefined, arrival: Date): Date | null;
+/** The deadline for the stay as it stands — i.e. of the SELECTED policy.
+ *  Kept as its own name because that is what a summary line means: not "some
+ *  policy allows this" but "what you have chosen allows this". */
+declare function freeCancellationUntil(policies: QuoteCancellationPolicy[], arrival: Date): Date | null;
+/** The same stay priced under ONE cancellation policy. `quote` is a real
+ *  GuestQuote branched off the base, so the UI can show its card, and hand the
+ *  branch on to a later step, without re-quoting the stay. */
+interface PolicyBranch {
+  id: string;
+  /** The branch quote — the base itself for the already-selected policy. */
+  quote: GuestQuote;
+  /** That quote flattened, so `view.card.total` is THIS policy's real price. */
+  view: QuoteView;
+}
+/**
+ * Price every selectable cancellation policy off ONE base quote, so a guest can
+ * compare the policies by what each actually costs rather than by a percentage.
+ *
+ * WHY REAL BRANCHES AND NOT ARITHMETIC. `markUpPercentage` looks like enough to
+ * compute the alternative price, and it is not: the modifier applies to the
+ * RENT, while taxes and fees ride along untouched, so the change it makes to
+ * the total is always smaller than the percentage says — and a guest who checks
+ * the number against the total would find the site's own figure wrong. The
+ * arithmetic is unavailable in any case: every amount the SDK returns is a
+ * locale-formatted string, so computing on one means parsing it back, which
+ * this file does for no other charge either. What the PMS prices is what the UI
+ * shows.
+ *
+ * `selectCancellationPolicy` does NOT mutate its input — it returns a new quote
+ * — so each policy can be branched off the same base and the branches held side
+ * by side. Costs one SDK call per policy MINUS one: the already-selected policy
+ * is the base quote itself. Sequential, because the API allows 1 req/s.
+ *
+ * A policy the PMS marks `available: false` is skipped rather than attempted:
+ * selecting it would fail by definition, and a burnt request inside a 1 req/s
+ * budget delays the ones that can succeed. It simply gets no branch, and the UI
+ * renders it as the unselectable row it already is.
+ */
+declare function pricePolicyBranches(base: GuestQuote, sdk: WebsiteSdk): Promise<PolicyBranch[]>;
+//#endregion
+//#region src/booking.d.ts
+/** Where the payment provider sends the guest back after an online payment
+ *  (relative — the SDK/PSP resolves it against the site origin). */
+declare const CHECKOUT_RETURN_PATH = "/buchen/bestaetigung";
+/** The checkout form's flat contact fields (the UI shape). `toBookingContact`
+ *  folds them into the SDK's nested BookingContact. */
+interface BookingContactForm {
+  forename: string;
+  surname: string;
+  /** Anrede ("Frau" / "Herr"); omitted when the guest picks none. */
+  title?: string | undefined;
+  street: string;
+  housenumber?: string | undefined;
+  postalcode: string;
+  city: string;
+  /** ISO 3166-1 alpha-2, e.g. "DE". */
+  countryCode: string;
+  email: string;
+  phone?: string | undefined;
+  note?: string | undefined;
+}
+interface PaymentLine {
+  label: string;
+  amount: string;
+}
+/** One payment entry, verbatim — a contractual step (Anzahlung / Restzahlung /
+ *  Rate / Kaution) or a way to settle the whole outstanding balance. */
+interface PaymentScheduleView {
+  /** SDK's stable kind, for programmatic behaviour ONLY. Everything the guest
+   *  reads comes from `label`: the SDK translates it, and a v10 installment is
+   *  not automatically a v9 prepayment. */
+  kind: BookingPaymentScheduleKind | "full_amount";
+  label: string;
+  /** Complete translated phrase, e.g. "Zahlbar bis zum 6. Februar 2027".
+   *  Render as-is — never parse it, never prefix another due-date label. It
+   *  stopped being a bare date in website-sdk 2.13.0, and it was never reliably
+   *  ISO before that either. */
+  dueOn?: string | undefined;
+  /** Where the payment happens, translated (v10 supplies it when the backend
+   *  states a payment location). Same rule: render, don't reformat. */
+  paymentAt?: string | undefined;
+  lines: PaymentLine[];
+  amount: string;
+  /** The PMS's own payment options — the SDK union (bank_transfer / redirect /
+   *  form_post / stripe_checkout), untouched. **EMPTY means informational:**
+   *  the SDK cannot perform this payment right now (a future step, on-site, or
+   *  external), so the card must not offer a button for it. */
+  options: BookingPaymentOption[];
+}
+/** A travel-insurance premium still to be settled WITH THE INSURER, from
+ *  `book().insurancePaymentOptions` — label and URL verbatim. Deliberately not
+ *  a `PaymentScheduleView`: those are the PMS's own steps, owed to the site's
+ *  operator and payable through the SDK. This one is a different contract with
+ *  a different recipient, and it leaves the site entirely. */
+interface InsurancePaymentLink {
+  label: string;
+  url: string;
+  description?: string | undefined;
+}
+interface BookingConfirmation {
+  bookingNumber: string;
+  /** The contractual steps, in backend order — what the guest owes and when. */
+  schedules: PaymentScheduleView[];
+  /** Ways to settle the COMPLETE outstanding balance at once (kind
+   *  `full_amount`), an ALTERNATIVE to the schedule above rather than an
+   *  addition to it. Kept apart because summing the two would double-count, and
+   *  because a synthesized alternative carries no deadline of its own — the
+   *  schedule's steps are where the dates live. */
+  alternatives: PaymentScheduleView[];
+  /** Empty unless insurance was actually booked AND the insurer returned a
+   *  payment page for it. Kept out of `schedules` and `alternatives` on
+   *  purpose: the premium is in neither, so a card that listed it among them
+   *  would misstate what is owed to whom (CONTRACT.md, "Travel insurance"). */
+  insurancePayments: InsurancePaymentLink[];
+}
+/**
+ * Create the booking. `quote` MUST be the live GuestQuote instance (with any
+ * service/policy selections applied). USER-initiated only — this reserves for
+ * real. Throws on transport/backend errors (the caller renders an honest
+ * retry message; nothing was necessarily booked when it throws).
+ */
+declare function submitBooking(quote: GuestQuote, contact: BookingContactForm, sdk: WebsiteSdk): Promise<BookingConfirmation>;
+/** True for the option kinds `submitPaymentOption` can perform in-browser
+ *  (redirect / form_post / stripe_checkout). Bank transfer is display-only. */
+declare function isSubmittableOption(option: BookingPaymentOption): option is SubmittableBookingPaymentOption;
+/** Perform an online payment option (redirects the browser to the PSP).
+ *  USER-initiated only.
+ *
+ *  Logged on failure, and this is the worst place in the flow to lose a reason:
+ *  by the time a payment option is on screen THE RESERVATION ALREADY EXISTS
+ *  (the SDK's `booking.md` says as much), so a failure here is an unpaid
+ *  booking, not a failed one. The checkout's catch discards the error entirely
+ *  — `.catch(() => setPayError(true))` — so without this a guest who cannot
+ *  pay leaves no trace at all, on a booking someone now has to chase. */
+declare function payWithOption(option: SubmittableBookingPaymentOption, sdk: WebsiteSdk): Promise<void>;
+//#endregion
+//#region src/booking-snapshot.d.ts
+/** Rental identity, parked by the checkout page (which has it from SSR) and
+ *  folded into the snapshot at book time — the SDK seam that writes the
+ *  snapshot never sees a rental name or a link. */
+declare const CHECKOUT_CONTEXT_KEY = "voffice:checkout-context";
+/** The finished record `/buchen/bestaetigung` reads. */
+declare const BOOKING_SNAPSHOT_KEY = "voffice:booking-return";
+/** One gallery image, in the SDK's own shape (`RentalGalleryImage` minus the
+ *  fields this page does not render). Stored so the confirmation can show the
+ *  unit rather than describe it — the guest booked a place, not a table. */
+interface SnapshotImage {
+  src: string;
+  srcset?: string | undefined;
+  alt: string;
+}
+interface CheckoutContext {
+  rentalName: string;
+  location?: string | undefined;
+  href?: string | undefined;
+  /** Capped at the same five the checkout's own summary strip shows. */
+  images?: SnapshotImage[] | undefined;
+}
+interface BookingSnapshotGuests {
+  adults: number;
+  children: number;
+  babies: number;
+  pets: number;
+}
+/** Every field but `bookingNumber` self-hides when absent — the return page
+ *  renders a row only for what it actually has, never an empty shell
+ *  (`DATA_SCHEMA.md`: "Optional field gates optional UI"). */
+interface BookingSnapshot {
+  bookingNumber: string;
+  rentalName?: string | undefined;
+  location?: string | undefined;
+  href?: string | undefined;
+  images?: SnapshotImage[] | undefined;
+  /** `YYYY-MM-DD` — the vocabulary the whole funnel already carries. */
+  start?: string | undefined;
+  end?: string | undefined;
+  guests?: BookingSnapshotGuests | undefined;
+  /** The SDK's own formatted total, verbatim. Never re-derived, never summed. */
+  total?: string | undefined;
+}
+/** Park the rental's identity for the return page. Called by the checkout page
+ *  on load — it is the last place in the flow that knows the rental by name. */
+declare function saveCheckoutContext(context: CheckoutContext): void;
+/**
+ * Write the return page's record. Called by `submitBooking` the moment the
+ * reservation exists — EARLIER than the SDK's "before submitting a payment
+ * option", because that is when the booking number is born, and a guest who
+ * settles by bank transfer never leaves the checkout at all.
+ *
+ * Never throws. The snapshot is a nicety; the booking is not.
+ */
+declare function saveBookingSnapshot(bookingNumber: string, quote: GuestQuote): void;
+//#endregion
+//#region src/checkout/insurance.d.ts
+/** The plan's documents as the checkout treats them: what it lists, what the
+ *  guest must open, and what makes a plan sellable at all read the SAME list,
+ *  so a hidden document can never end up required-but-unlisted (which would be
+ *  a gate the guest cannot close). */
+declare function shownInsuranceResources(option: QuoteInsuranceOption): {
+  label: string;
+  url: string;
+}[];
+/** The insurance products a checkout can actually complete. Two gates, and
+ *  this filter is where the layer's capability is declared — a site that adds a
+ *  missing flow adds it HERE, upstream, never in its own copy.
+ *
+ *  1. **Technical.** Products that select with the id alone and book WITH the
+ *     rental booking. One that demands per-traveler data first (traveler forms,
+ *     pre-contract, SEPA mandate, a post-booking insurance call) needs a flow
+ *     this layer does not implement — offering it would dead-end the guest.
+ *
+ *  2. **Legal.** The product must carry its `resources`, the insurer's
+ *     pre-contractual documents (see "Mandatory pre-contractual documents"
+ *     below for which duties they discharge). A product the feed sends WITHOUT
+ *     them cannot be concluded lawfully here, so it self-hides rather than
+ *     being sold undocumented — the same rule as (1), applied to a legal
+ *     precondition instead of a technical one. */
+declare function selectableInsuranceOptions(insurance: QuoteInsurance): QuoteInsuranceOption[];
+/** The selected plan, but only when it is one the guest could actually pick
+ *  here — so no price row can name a product the section above never showed. */
+declare function selectedInsuranceOption(insurance: QuoteInsurance | undefined): QuoteInsuranceOption | undefined;
+/** The identity of an insurance PRODUCT, as opposed to the id of one priced
+ *  variant of it.
+ *
+ *  An insurer may band its tariffs by trip value, and then a plan id is not the
+ *  product — it is the product AT one price. The same tariff comes back under a
+ *  new id and a new premium the moment the total crosses a band. URV is the
+ *  observed case: "RRV ohne SB Deutschland" is `RROR0625` at 56,00 € up to
+ *  roughly 1.250 €, `RROR0725` at 65,00 € above that, `RROR0825` at 74,00 €
+ *  above that again. Every extra, every policy markup and every stay change can
+ *  cross a band, and each of them re-prices the quote — which is what makes the
+ *  SDK re-fetch the insurer's plan list against the new total.
+ *
+ *  The label is what survives that: the same string in every band, and the name
+ *  the guest actually chose, since it is what the radio shows. */
+declare function insuranceProductKey(option: QuoteInsuranceOption): string;
+/** The plan id to re-apply onto a re-priced quote, or null when there is
+ *  nothing to do — no choice, already applied, or a product this feed no longer
+ *  offers as a selectable one. The last case is why the feed is checked rather
+ *  than the call simply attempted: a doomed selection would spend one of the
+ *  rate-limited requests to be refused, and the guest ends up on "keine
+ *  Versicherung" either way.
+ *
+ *  Matched by id first, then by product (see insuranceProductKey). That
+ *  fallback is what keeps a banded re-price from silently un-selecting
+ *  insurance the feed still sells: the SDK carries a selection across its
+ *  refresh only on an exact id match, so a renamed-but-identical tariff reads
+ *  to it as a plan that vanished, and a guest who only added a towel package
+ *  lands back on "keine Versicherung". Re-applying picks the SAME product at
+ *  its new premium — the one they would in fact be buying — and that premium is
+ *  on screen in the radio, in the summary rail and above the submit button, so
+ *  nothing about the change is hidden.
+ *
+ *  Checked against the SELECTABLE options, not the raw list: a plan the fresh
+ *  feed carries without its documents (or newly demanding traveler data) is one
+ *  the section no longer shows, so re-applying it would leave the quote
+ *  carrying an insurance the page neither displays nor can take a document
+ *  confirmation for. */
+declare function insuranceIdToReapply(fresh: QuoteView, wanted: QuoteInsuranceOption | undefined): string | null;
+/** Progress through the document step. Held by the orchestration hook because
+ *  the submit button, a card away, is gated on it. */
+interface InsuranceDocsState {
+  /** URLs opened so far — keyed by URL, not by plan. Plans routinely share
+   *  every file but the IPID, and having received an identical document does
+   *  not un-happen when the guest switches tariff. Keying by URL also survives
+   *  a re-quote, which returns fresh option objects for the same product. */
+  opened: ReadonlySet<string>;
+  /** Product whose documents the guest confirmed receiving (keyed by
+   *  insuranceProductKey, not by plan id); null = none yet. Product-bound on
+   *  purpose, so a tariff switch demands a fresh acknowledgement while the
+   *  opened files above carry over. By PRODUCT rather than by plan for the same
+   *  reason the selection is carried by product: a banded re-price hands back
+   *  the identical documents under a new plan id, and making the guest re-tick
+   *  a box for files they already have — because a towel package moved the
+   *  total — would be friction with nothing behind it. */
+  confirmedProduct: string | null;
+}
+declare const NO_INSURANCE_DOCS: InsuranceDocsState;
+/** True while a chosen plan's document step is unfinished. No plan chosen (or
+ *  "keine Versicherung") is never blocking — the duty attaches to the insurance
+ *  contract, not to the stay. */
+declare function insuranceDocsPending(option: QuoteInsuranceOption | undefined, docs: InsuranceDocsState): boolean;
+//#endregion
+//#region src/checkout/stay.d.ts
+interface Stay {
+  start: Date;
+  end: Date;
+  adults: number;
+  children: number;
+  childrenAges: number[];
+  babies: number;
+  pets: number;
+}
+/** Date → `YYYY-MM-DD` in LOCAL time — the vocabulary the URL handover and the
+ *  SDK both use. Local on purpose (matches date-fns `format(date,
+ *  "yyyy-MM-dd")`, which the sites' own lib/dates.ts uses): a calendar day
+ *  picked in the browser must not shift across midnight UTC. */
+declare function isoDate(date: Date): string;
+declare function occupancyOf(stay: Stay): QuoteOccupancy;
+/** The identity of a stay for "is the shown price still the shown stay"
+ *  comparisons — every field that changes the quote, in one string. */
+declare function stayKeyOf(stay: Stay): string;
+/** The stay as URL search params (`start`/`end`/`adults`/… — the same
+ *  vocabulary the rental page reads + writes). */
+declare function stayParams(stay: Stay): string;
+//#endregion
+//#region src/checkout/createCheckoutFlow.d.ts
+/**
+ * The checkout's orchestration — everything between "a complete stay is in
+ * hand" and "the guest is booked and paying", with no markup and no framework.
+ *
+ * The flow owns the quote lifecycle (initial load, re-quote on stay change,
+ * supersession), the selection mutations (extras / insurance / voucher /
+ * policy re-apply), the § 7 VVG document gate, booking submit and payment —
+ * the parts that must be correct on every site and update mechanically. The
+ * UI owns stay EDITING (calendar, guest panel, URL read/write), copy, and
+ * every pixel. A UI subscribes to `subscribe`, reads `getState`, calls the
+ * actions, and feeds stay/policy changes through `update` (React: one
+ * useSyncExternalStore — see the README).
+ *
+ * ONE flow instance owns the whole thing because the live `GuestQuote` that
+ * `booking.book` requires is not serializable across a navigation: the
+ * consumer re-quotes from the URL handover on mount and the flow keeps the
+ * instance in memory through extras / policy / voucher selections until
+ * book().
+ *
+ * ⚠ `book()` creates a REAL booking; `pay()` starts a REAL payment. Both are
+ * strictly user-initiated — never automate them.
+ */
+type CheckoutPhase = {
+  kind: "loading";
+} | {
+  kind: "ready";
+} | {
+  kind: "unavailable";
+  reason: string;
+} | {
+  kind: "error";
+};
+/** The user-facing strings the flow itself needs — the reasons it reports when
+ *  the backend gives none, or gives one that would be a false statement. Copy,
+ *  so it stays per-site. */
+interface CheckoutFlowMessages {
+  /** Shown INSTEAD of the SDK's localized unavailability reason when the quote
+   *  failed on a rate-configuration fault (AmbiguousMultiRate /
+   *  UnresolvableMultiRate) — the stay is free; only the price cannot be
+   *  resolved, so the availability wording would be a false statement. */
+  rateFault: string;
+  /** Fallback when an unavailable result carries no reason of its own. */
+  unavailable: string;
+  /** Inline issue line when a RE-quote (not the initial load) failed on transport. */
+  quoteRefreshFailed: string;
+  /** Voucher could not be applied at all (transport / stay unavailable). */
+  voucherFailed: string;
+  /** Voucher was processed and rejected / not recognized. */
+  voucherRejected: string;
+}
+interface CheckoutFlowOptions {
+  rentalId: string;
+  /** The site's SDK accessor (one instance for the flow's lifetime — quote +
+   *  selections + book share its queue and 1 req/s rate limit). The flow never
+   *  disposes it; the owner does. */
+  getSdk: () => WebsiteSdk;
+  /** The current COMPLETE stay, or null while none is in hand (mid-edit, URL
+   *  handover missing). The flow re-quotes whenever it changes. */
+  stay: Stay | null;
+  /** The cancellation rate chosen a step earlier (`?policy=` handover). A SEED
+   *  for the first quote, not the source of truth: once a quote exists, the
+   *  live quote's own `selected` flag is. Null means "whatever the PMS
+   *  pre-selects", which is also what an unknown id degrades to. */
+  chosenPolicy: string | null;
+  /**
+   * Which of a fresh quote's policies may be treated as OFFERED for the
+   * `chosenPolicy` re-apply — REQUIRED, because this is the enforcement point
+   * for the whole offer-withdrawal rule: a rate stops being an offer when the
+   * stay moves inside the standard rate's cancellation window, at which point
+   * the cheaper non-refundable one is the identical booking for less. Every
+   * route onto the checkout passes through this check (a stale link, a
+   * hand-built `?policy=`, an in-page date edit), so all of them lapse to the
+   * PMS pre-selection together.
+   */
+  filterOfferedPolicies: (policies: QuoteCancellationPolicy[], arrival: Date) => QuoteCancellationPolicy[];
+  messages: CheckoutFlowMessages;
+  /** Called when a quote returns `AmbiguousMultiRate` / `UnresolvableMultiRate`
+   *  — a PMS rate-configuration fault, not a booked-out stay. Route these to
+   *  monitoring or site operations. */
+  onRateConfigurationFault?: ((info: {
+    code: QuoteUnavailableCode;
+    rentalId: string;
+  }) => void) | undefined;
+}
+interface CheckoutIssue {
+  /** The stayKey the issue belongs to — a different stay re-arms the loop. */
+  key: string;
+  reason: string;
+  /** Transport errors offer a manual retry; unavailability does not. */
+  retryable: boolean;
+}
+/** Everything a UI renders. A new object per change; unchanged otherwise, so
+ *  `useSyncExternalStore` and friends can compare by reference. */
+interface CheckoutFlowState {
+  phase: CheckoutPhase;
+  view: QuoteView | null;
+  counts: Record<string, number>;
+  busy: boolean;
+  issue: CheckoutIssue | null;
+  selectionError: string | null;
+  quotedKey: string | null;
+  stayKey: string | null;
+  /** A re-quote is pending: the shown price does not match the shown stay. */
+  pricePending: boolean;
+  /** Booking is blocked (stale price, in-flight mutation, issue, or documents pending). */
+  blocked: boolean;
+  chosenInsurance: QuoteInsuranceOption | undefined;
+  insuranceDocs: InsuranceDocsState;
+  documentsPending: boolean;
+  voucherApplied: string | null;
+  voucherError: string | null;
+  bookState: "idle" | "submitting" | "error";
+  confirmation: BookingConfirmation | null;
+  payBusyKey: string | null;
+  payError: boolean;
+}
+/** The actions a UI calls. Stable functions for the flow's lifetime. */
+interface CheckoutFlowActions {
+  changeService(id: string, delta: 1 | -1): void;
+  selectInsurance(id: string | null): void;
+  openInsuranceDoc(url: string): void;
+  confirmInsuranceDocs(productKey: string, confirmed: boolean): void;
+  applyVoucher(code: string | null): void;
+  /** ⚠ USER-initiated only: creates a real booking. */
+  book(contact: BookingContactForm): void;
+  /** ⚠ USER-initiated only: redirects to the real payment provider. */
+  pay(key: string, option: PaymentScheduleView["options"][number]): void;
+  clearIssue(): void;
+}
+interface CheckoutFlow extends Store<CheckoutFlowState>, CheckoutFlowActions {
+  /** Feed the UI's current inputs. `stay` and `chosenPolicy` drive the
+   *  re-quote; messages and callbacks are read at call time. */
+  update(options: CheckoutFlowOptions): void;
+  /** Arm the auto-quote. Idempotent; call once the UI is mounted. */
+  start(): void;
+  /** Cancel pending work and drop every in-flight result. */
+  dispose(): void;
+}
+/** What a UI binding hands to the rendering code: the state plus the actions. */
+type CheckoutFlowApi = CheckoutFlowState & CheckoutFlowActions;
+declare function createCheckoutFlow(initialOptions: CheckoutFlowOptions): CheckoutFlow;
+//#endregion
+//#region src/checkout/card-order.d.ts
+declare function stabilizeCardOrder(view: QuoteView, order: Map<string, number>): QuoteView;
+//#endregion
+//#region src/checkout/validation.d.ts
+/**
+ * Contact-form field validation — the checkout's data-quality behavior,
+ * framework-free.
+ *
+ * Extracted from the sites' checkout island (`CheckoutFlow.tsx`). The RULES live here so every site validates a booking
+ * contact the same way; the MESSAGES are copy and stay per-site — every
+ * function takes them as a parameter (the site's `CheckoutFlowCopy` object
+ * satisfies `ValidationMessages` structurally, so skins pass their merged copy
+ * straight through).
+ */
+/** The subset of the checkout copy the validators read. A site's full copy
+ *  object satisfies this structurally. */
+interface ValidationMessages {
+  forenameRequired: string;
+  surnameRequired: string;
+  streetRequired: string;
+  cityRequired: string;
+  postalcodeRequired: string;
+  emailRequired: string;
+  emailInvalid: string;
+  phoneInvalid: string;
+  phoneNeedsDialCode: string;
+  postalcodeInvalidDE: string;
+  postalcodeInvalidAT: string;
+  postalcodeInvalidCH: string;
+  streetHouseNumberWarning: string;
+}
+declare function normalizePhone(raw: string, dial?: string): string;
+declare function phoneError(raw: string, dial: string, c: ValidationMessages): string | undefined;
+declare function emailError(raw: string, c: ValidationMessages): string | undefined;
+declare function postalcodeError(raw: string, country: string, c: ValidationMessages): string | undefined;
+declare function streetWarning(raw: string, c: ValidationMessages): string | undefined;
+declare const VALIDATED_FIELDS: readonly ["forename", "surname", "email", "phone", "street", "postalcode", "city"];
+/** Validate one named field. Takes the selected COUNTRY plus its calling code
+ *  (`dial`): two validators depend on the country — the phone via the dial
+ *  code, the PLZ via its format rule. The dial code is passed in rather than
+ *  looked up because the ISO→dial mapping lives with the site's country
+ *  register (its localized "Land" options), not here. */
+declare function fieldError(name: string, value: string, country: string, dial: string, c: ValidationMessages): string | undefined;
+/** Country options in the shape the site's country register provides —
+ *  `[code, label]` pairs, a featured group plus the full ISO register. Kept
+ *  structural so the site's own `CountryGroups` type satisfies it. */
+interface CountryGroupsLike {
+  featured: ReadonlyArray<readonly [string, string]>;
+  all: ReadonlyArray<readonly [string, string]>;
+}
+declare function detectCountry(countries: CountryGroupsLike): string;
+//#endregion
+//#region src/checkout/structure.d.ts
+/**
+ * The checkout's STRUCTURAL requirements — what must be on screen, in what
+ * order, regardless of who produced the markup.
+ *
+ * WHY THIS EXISTS. Headless holds the RULES (the § 7 VVG document gate, the
+ * stale-price booking guard) but no markup, so a site that renders its own
+ * checkout UI can silently drop a legal obligation — the § 312j BGB
+ * Button-Lösung wording, the insurance documents listed before the guest's
+ * confirmation, the price stated directly above the order button — and every
+ * unit test still passes. This module is a contract over the RENDERED result,
+ * checked by the platform's publish gate for imported and custom checkouts
+ * alike.
+ *
+ * Two halves:
+ *   - `CHECKOUT_PARTS`: the `data-part` vocabulary. Imported components carry
+ *     these attributes; a site's own markup must keep them so the gate (and
+ *     a site's own CSS) can find the elements.
+ *   - `CHECKOUT_STRUCTURE` + `assertCheckoutStructure(root)`: the requirements
+ *     and a pure DOM check the smoke suite runs against the rendered checkout
+ *     (a browser page or a jsdom document). Every requirement names the legal
+ *     basis it exists for, so a failure message tells the reader WHY.
+ */
+declare const CHECKOUT_PARTS: {
+  /** The one place the guest is told the price they are about to owe. */
+  readonly priceTotal: "checkout-price-total";
+  /** The § 312j order button. */
+  readonly submit: "checkout-submit";
+  /** The terms line (AGB + privacy triggers). */
+  readonly terms: "checkout-terms";
+  /** One link per mandatory insurance document (§ 7 VVG). */
+  readonly insuranceDocument: "checkout-insurance-document";
+  /** The guest's receipt confirmation for those documents. */
+  readonly insuranceConfirm: "checkout-insurance-confirm";
+};
+type CheckoutPart = (typeof CHECKOUT_PARTS)[keyof typeof CHECKOUT_PARTS];
+/** German "kostenpflichtig bestellen"-class labels the courts have accepted
+ *  for § 312j Abs. 3 BGB. The check is on the RENDERED button text, so a site
+ *  may re-voice the label — but only within this class. */
+declare const BUTTON_SOLUTION_PATTERN: RegExp;
+declare const CHECKOUT_STRUCTURE: {
+  readonly "submit-present": {
+    readonly basis: "§ 312j Abs. 3 BGB (Button-Lösung)";
+    readonly description: "exactly one order button carries data-part=checkout-submit";
+  };
+  readonly "submit-wording": {
+    readonly basis: "§ 312j Abs. 3 BGB (Button-Lösung)";
+    readonly description: "the order button's visible text is a 'zahlungspflichtig buchen'-class label";
+  };
+  readonly "total-before-submit": {
+    readonly basis: "§ 312j Abs. 2 BGB (price stated immediately before the order)";
+    readonly description: "a data-part=checkout-price-total precedes the order button in DOM order";
+  };
+  readonly "terms-before-submit": {
+    readonly basis: "§ 312d BGB / Art. 13 DSGVO (terms + privacy notice before contracting)";
+    readonly description: "a data-part=checkout-terms precedes the order button";
+  };
+  readonly "insurance-docs-before-confirm": {
+    readonly basis: "§ 7 Abs. 1 VVG, § 4 VVG-InfoV (documents before the declaration)";
+    readonly description: "when an insurance confirmation is rendered, at least one insurance document precedes it in DOM order";
+  };
+};
+type CheckoutRequirement = keyof typeof CHECKOUT_STRUCTURE;
+interface StructureViolation {
+  requirement: CheckoutRequirement;
+  basis: string;
+  detail: string;
+}
+declare function assertCheckoutStructure(root: ParentNode): StructureViolation[];
+//#endregion
+export { BOOKING_SNAPSHOT_KEY, BUTTON_SOLUTION_PATTERN, BookingConfirmation, BookingContactForm, BookingSnapshot, BookingSnapshotGuests, CHECKOUT_CONTEXT_KEY, CHECKOUT_PARTS, CHECKOUT_RETURN_PATH, CHECKOUT_STRUCTURE, CheckoutContext, type CheckoutFlow, type CheckoutFlowActions, type CheckoutFlowApi, type CheckoutFlowMessages, type CheckoutFlowOptions, type CheckoutFlowState, type CheckoutIssue, type CheckoutPart, type CheckoutPhase, type CountryGroupsLike, type InsuranceDocsState, InsurancePaymentLink, Listener, MULTI_RATE_CODES, NO_INSURANCE_DOCS, PaymentLine, PaymentScheduleView, PolicyBranch, PriceQuote, QuoteAddonService, QuoteCancellationPolicy, QuoteInsurance, QuoteInsuranceOption, QuoteLine, QuoteOccupancy, QuotePolicyRule, QuoteResult, QuoteSelectionResult, QuoteUnavailableCode, QuoteView, QuoteVoucher, SnapshotImage, type Stay, Store, type StructureViolation, Unsubscribe, VALIDATED_FIELDS, type ValidationMessages, WebsiteSdk, WritableStore, adaptGuestQuote, addQuoteService, assertCheckoutStructure, clearQuoteServices, createCheckoutFlow, createStore, describeSdkError, detectCountry, emailError, fetchQuote, fieldError, freeCancellationUntil, fullRefundRule, insuranceDocsPending, insuranceIdToReapply, insuranceProductKey, isRateConfigurationFault, isSubmittableOption, isoDate, logSdkFailure, normalizePhone, occupancyOf, payWithOption, phoneError, policyFreeCancellationUntil, postalcodeError, pricePolicyBranches, removeQuoteService, saveBookingSnapshot, saveCheckoutContext, selectQuoteInsurance, selectQuotePolicy, selectableInsuranceOptions, selectedInsuranceOption, shownInsuranceResources, stabilizeCardOrder, stayKeyOf, stayParams, streetWarning, submitBooking };