@v-office/website-sdk 2.12.0 → 2.14.0

package/instructions/CHANGELOG.md

@@ -4,6 +4,8 @@ This file is the versioned changelog index for the website SDK instructions.
 
 ## Versions
 
+- `versions/2.14.0/CHANGELOG.md`: `@v-office/website-sdk` 2.14.0 release notes.
+- `versions/2.13.0/CHANGELOG.md`: `@v-office/website-sdk` 2.13.0 release notes.
 - `versions/2.12.0/CHANGELOG.md`: `@v-office/website-sdk` 2.12.0 release notes.
 - `versions/2.11.0/CHANGELOG.md`: `@v-office/website-sdk` 2.11.0 release notes.
 - `versions/2.10.0/CHANGELOG.md`: `@v-office/website-sdk` 2.10.0 release notes.

package/instructions/MIGRATION.md

@@ -4,6 +4,8 @@ This file is the versioned migration index for the website SDK instructions.
 
 ## Available Guides
 
+- `versions/2.14.0/MIGRATION.md`: migrate from `@v-office/website-sdk` 2.13.0 to 2.14.0.
+- `versions/2.13.0/MIGRATION.md`: migrate from `@v-office/website-sdk` 2.12.0 to 2.13.0.
 - `versions/2.12.0/MIGRATION.md`: migrate from `@v-office/website-sdk` 2.11.0 to 2.12.0.
 - `versions/2.11.0/MIGRATION.md`: migrate from `@v-office/website-sdk` 2.10.0 to 2.11.0.
 - `versions/2.10.0/MIGRATION.md`: migrate from `@v-office/website-sdk` 2.9.0 to 2.10.0.

package/instructions/README.md

@@ -1,7 +1,7 @@
 # Website SDK Instructions
 
 These instructions describe the current source targeted for
-`@v-office/website-sdk` 2.12.0. Package versions remain unchanged until the release
+`@v-office/website-sdk` 2.14.0. Package versions remain unchanged until the release
 workflow performs the coordinated core and website bumps.
 
 Use this directory as the consumer-facing reference for the package:
@@ -18,6 +18,12 @@ Use this directory as the consumer-facing reference for the package:
 - `document-structured-json.md`: `sdk.static.documents.getTermsAndPrivacyPolicy` and structured document JSON rendering rules.
 - `CHANGELOG.md`: versioned changelog index.
 - `MIGRATION.md`: versioned migration index.
+- `versions/2.14.0/`: 2.14.0 catalog-backed v9 property types and options,
+  corrected option/count rendering and translations, and the 2.13.0-to-2.14.0
+  migration guide.
+- `versions/2.13.0/`: 2.13.0 static search capability discovery, shared v9/v10
+  booking-payment output, corrected remaining-payment deadlines, opaque booking
+  credentials, and the 2.12.0-to-2.13.0 migration guide.
 - `versions/2.12.0/`: 2.12.0 legacy-v9 search discounts, empty-query browsing,
   and flexible-period rejection; quote booking-card cleanup; and v10 modifier
   guidance, plus the 2.11.0-to-2.12.0 migration guide.
@@ -42,7 +48,9 @@ Use this directory as the consumer-facing reference for the package:
 pnpm add @v-office/website-sdk
 ```
 
-The package is ESM-only and exports the root SDK facade from `@v-office/website-sdk`.
+The package is ESM-only. It exports the SDK facade from `@v-office/website-sdk`
+and instance-independent search capability helpers from
+`@v-office/website-sdk/capabilities/search`.
 
 ## Quick Start
 
@@ -82,5 +90,5 @@ website-sdk --backend v10 search --locale de-DE --query "adults=2" --sort '{"by"
 ```
 
 Config file examples in these docs use the flat `WebsiteSDKConfig` shape introduced
-in 2.0.0 and kept in 2.12.0. v10 config additionally requires `searchEndpoint` as
+in 2.0.0 and kept in 2.14.0. v10 config additionally requires `searchEndpoint` as
 of 2.5.0.

package/instructions/booking.md

@@ -78,47 +78,63 @@ Sample:
 ```json
 {
   "bookingNumber": "B-2026-0001",
-  "guestToken": "guest-token",
-  "paymentSchedules": [
-    {
-      "label": "Deposit",
-      "dueOn": "2026-06-15",
-      "lines": [
-        {
-          "label": "Deposit",
-          "amount": "300.00 EUR"
-        }
-      ],
-      "total": "300.00 EUR",
-      "paymentOptions": [
-        {
-          "kind": "bank_transfer",
-          "label": "Bank transfer",
-          "holder": "Example GmbH",
-          "iban": "DE02120300000000202051",
-          "swiftOrBic": "BYLADEM1001",
-          "remittanceText": "B-2026-0001"
-        },
-        {
-          "kind": "redirect",
-          "provider": "adyen",
-          "label": "Credit card",
-          "url": "https://checkout.example.com"
-        },
-        {
-          "kind": "stripe_checkout",
-          "provider": "stripe",
-          "label": "Credit card",
-          "sessionId": "cs_live_a1Upmvi1v62AdILeDZl4l",
-          "accountId": "acct_1MpAB7AFrTg9gw7b"
-        }
-      ]
-    }
-  ],
-  "insurancePaymentOptions": []
+  "payment": {
+    "schedule": [
+      {
+        "kind": "prepayment",
+        "label": "Down payment",
+        "amount": "€76.00",
+        "dueOn": "Payable until August 19, 2026",
+        "paymentOptions": [
+          {
+            "kind": "bank_transfer",
+            "label": "Bank transfer",
+            "holder": "Example GmbH",
+            "iban": "DE02120300000000202051",
+            "swiftOrBic": "BYLADEM1001",
+            "remittanceText": "Booking number: B-2026-0001"
+          }
+        ]
+      },
+      {
+        "kind": "remaining_payment",
+        "label": "Remaining payment",
+        "amount": "€304.00",
+        "dueOn": "Payable until February 6, 2027"
+      }
+    ],
+    "alternatives": [
+      {
+        "kind": "full_amount",
+        "label": "Total payment",
+        "amount": "€380.00",
+        "paymentOptions": [
+          {
+            "kind": "bank_transfer",
+            "label": "Bank transfer",
+            "holder": "Example GmbH",
+            "iban": "DE02120300000000202051",
+            "swiftOrBic": "BYLADEM1001",
+            "remittanceText": "Booking number: B-2026-0001"
+          }
+        ]
+      }
+    ]
+  }
 }
 ```
 
+`payment.schedule` contains the remaining contractual payment steps known to the backend. Its `kind` is one of `prepayment`, `remaining_payment`, `installment`, or `deposit`. `v9` emits named prepayment and remaining-payment steps; `v10` emits its backend-provided installment and deposit steps.
+
+`payment.alternatives` contains ways to settle the complete outstanding balance. A `full_amount` alternative has no inferred deadline. `dueOn`, `paymentAt`, labels, amounts, and line amounts are already translated and formatted for the booking locale.
+
+`paymentOptions` is present only when the SDK can currently perform that payment. Future or on-site steps remain visible without payment options.
+
+An optional `insurancePaymentOptions` array is returned only when post-booking insurance payment is available.
+
+Sites upgrading from 2.12.0 must replace the former `paymentSchedules` output. See
+`versions/2.13.0/MIGRATION.md`.
+
 Payment option variants:
 
 - `bank_transfer`: display-only payment details.
@@ -153,13 +169,13 @@ try {
 
 Online payment providers return the guest to a URL derived from `relativeRedirectUrl`. Stripe returns to that path with `payment=stripe&success=true` after payment and `payment=stripe&cancel=true` after cancellation, so the path must exist in your site and should read those query parameters.
 
-`relativeRedirectUrl` is supplied before the reservation exists, so the return URL cannot carry the booking number or guest token. Persist whatever the return page needs, for example in `sessionStorage`, before submitting a payment option.
+`relativeRedirectUrl` is supplied before the reservation exists, so the return URL cannot carry the booking number. Persist whatever the return page needs, for example in `sessionStorage`, before submitting a payment option.
 
 A successful return means the provider sent the browser back, not that the payment has settled. Confirmation reaches vOffice through the provider's webhook.
 
 ## Configuration
 
-Booking requests are rate-limited to one backend request per second with a queue size of five. `v9` books through the v0 `book` action and initializes one Stripe Checkout Session per payment schedule option when the property has Stripe enabled. `v10` books through GraphQL and initializes Adyen redirect payment options.
+Booking requests are rate-limited to one backend request per second with a queue size of five. `v9` books through the v0 `book` action and initializes Stripe only for currently payable choices when the property has Stripe enabled. `v10` books through GraphQL, preserves all remaining payment steps for display, and initializes Adyen for the next payable online step and the full-outstanding alternative.
 
 ## CLI Usage
 

package/instructions/quote.md

@@ -393,16 +393,18 @@ quote = await sdk.live.quote.selectInsurancePayment({
 });
 ```
 
-After the rental booking is created, complete insurance booking with the booking number and guest token:
+After the rental booking is created, complete insurance booking with the opaque booking result. Keep the live result object; its private backend credentials are intentionally not serialized:
 
 ```ts
 const insuranceBooking = await sdk.live.quote.bookInsurance({
   quote,
-  bookingNumber: booking.bookingNumber,
-  guestToken: booking.guestToken,
+  booking,
 });
 ```
 
+This is a breaking change in 2.13.0. The former public `guestToken` input is no
+longer used; see `versions/2.13.0/MIGRATION.md`.
+
 `v9` supports real insurance option refresh, pre-contract, payment selection, and booking. `v10` currently returns a no-insurance placeholder and insurance actions resolve as not required.
 
 ## Configuration

package/instructions/rentals.md

@@ -54,7 +54,7 @@ Sample item:
     "headline": "Holiday apartment near the sea",
     "description": "Short localized rental description."
   },
-  "highlights": ["2 bedrooms", "WiFi", "Parking"],
+  "highlights": ["2 bedrooms", "Wi-Fi", "Parking"],
   "attributes": [
     {
       "label": "Amenities",
@@ -87,6 +87,51 @@ Sample item:
 
 Optional fields include `scope`, `address`, `property`, `rooms`, `roomSummary`, `vicinity`, and `reviews`.
 
+### Legacy v9 Built-In Attributes
+
+From 2.14.0, built-in v9 property types and ordered option values come from the
+vOffice property catalog rather than example-value inference. The SDK keeps
+observed-only fields for compatibility, but examples do not redefine catalog
+fields.
+
+v9 `OPT` values are zero-based numeric indexes. The SDK resolves them to
+localized display text before adding them to `attributes`, `highlights`, or
+`vicinity`. For example:
+
+```text
+youthgroups = 0 → Jugendgruppen: willkommen
+youthgroups = 1 → Jugendgruppen: nicht erlaubt
+youthgroups = 2 → Jugendgruppen: auf Anfrage
+```
+
+An option index of `0` is a valid value, not Boolean `false`. Invalid,
+fractional, negative, and out-of-range indexes are omitted.
+
+Source-defined v9 `INT` values retain their numeric value, including `1`. Known
+count attributes use localized singular and plural nouns:
+
+```text
+bedrooms = 1 → 1 Schlafzimmer
+bedrooms = 2 → 2 Schlafzimmer
+bedrooms = 1 → 1 bedroom
+bedrooms = 2 → 2 bedrooms
+```
+
+Boolean behavior is unchanged: disabled values are omitted and enabled values
+are rendered as the localized label.
+
+Translation overrides use these key forms:
+
+```text
+RentalAttributes.<attribute>.label
+RentalAttributes.<attribute>.option.<zero-based-index>
+RentalAttributes.<attribute>.count.one
+RentalAttributes.<attribute>.count.other
+```
+
+See `versions/2.14.0/CHANGELOG.md` and
+`versions/2.14.0/MIGRATION.md`.
+
 ### Review Items
 
 Each review item contains at least `rating` or `text`. `id`, `author`, `label`, and `createdAt` are optional:

package/instructions/search.md

@@ -77,6 +77,28 @@ Common stable query keys:
 - Occupancy: `adults`, `children`, `childrenAges`, `babies`, `pets`, `petsCount`.
 - Filters: use `searchParameterQueryKey` values from `sdk.static.filter.getFilters(...)`.
 
+### Static Backend Capabilities
+
+Search capabilities that only depend on a backend name are available without
+constructing an SDK:
+
+```ts
+import {
+  getSupportedPeriodQueryKeys,
+  supportsFlexiblePeriodSearch,
+} from "@v-office/website-sdk/capabilities/search";
+
+supportsFlexiblePeriodSearch("v9"); // false
+supportsFlexiblePeriodSearch("v10"); // true
+
+getSupportedPeriodQueryKeys("v9").has("month"); // false
+getSupportedPeriodQueryKeys("v10").has("month"); // true
+```
+
+The returned read-only set contains the stable period query keys accepted by the
+selected backend, including aliases such as `from` and `till`. Key support does
+not replace validation of complete query combinations.
+
 ## Query Structure
 
 The `query` field is a URL query-string style value without a leading `?`.

package/instructions/versions/2.13.0/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog: 2.13.0
+
+This release adds static backend search capability discovery and replaces the
+ambiguous flat booking payment schedule with a shared, presentation-ready payment
+model for v9 and v10. It preserves every known remaining payment step, separates
+contractual steps from full-payment alternatives, and keeps backend credentials
+out of the public booking output.
+
+## Added
+
+- `@v-office/website-sdk/capabilities/search` exposes pure, instance-independent
+  helpers for checking flexible-period support and the supported period query keys
+  for a backend.
+- `BookingOutput.payment.schedule` contains the remaining contractual payment
+  steps known after booking.
+- `BookingOutput.payment.alternatives` contains optional ways to settle the
+  complete outstanding balance.
+- Schedule entries have a stable `kind`: `prepayment`, `remaining_payment`,
+  `installment`, or `deposit`.
+- Full-payment alternatives use `kind: "full_amount"`.
+- v10 booking output includes all remaining online, on-site, and external payment
+  steps instead of exposing only the next online step.
+- v10 schedule entries can include translated `paymentAt` text derived from the
+  backend payment location and recipient.
+- Legacy v9 now preserves its independently supplied remaining-payment amount and
+  deadline.
+
+## Changed
+
+- `dueOn` is now a complete translated, long-form display string such as
+  `Zahlbar bis zum 6. Februar 2027`.
+- Schedule and alternative amounts use the `amount` field and remain
+  locale-formatted display strings.
+- `paymentOptions` is present on a schedule entry only when the SDK can currently
+  perform that payment. Informational future, on-site, and external steps remain
+  visible without payment options.
+- A synthesized v9 full-payment alternative no longer copies the prepayment
+  deadline. An explicit backend total deadline can still be retained.
+- v10 initializes Adyen only for the next payable online step and the
+  full-outstanding alternative.
+- v9 initializes Stripe only for currently payable choices.
+- Post-booking insurance now receives the opaque booking result:
+
+  ```ts
+  await sdk.live.quote.bookInsurance({ quote, booking });
+  ```
+
+## Removed
+
+- `BookingOutput.paymentSchedules`
+- Public `BookingOutput.guestToken`
+- ISO-like or locale-short date assumptions for booking payment output
+
+The private v9 guest token remains attached to the live opaque booking object and
+is used internally when completing insurance. It is not enumerable or
+serializable.
+
+## Backend Mapping
+
+- v9 `prepayment` becomes `kind: "prepayment"`.
+- v9 `rest` becomes `kind: "remaining_payment"`.
+- v9 `total` becomes a `full_amount` alternative.
+- v10 `INSTALLMENT` becomes `kind: "installment"`.
+- v10 `DEPOSIT` becomes `kind: "deposit"`.
+- v10 `financials.outstanding` becomes a `full_amount` alternative when it is a
+  distinct payable choice.
+
+## Migration Impact
+
+This is a breaking output and insurance-input change. Consumers must:
+
+1. Replace reads of `paymentSchedules` with `payment.schedule` and
+   `payment.alternatives`.
+2. Read `amount` instead of the former schedule `total`.
+3. Treat schedule `paymentOptions` as optional.
+4. Render `dueOn`, `paymentAt`, labels, amounts, and line amounts directly without
+   reparsing or reformatting them.
+5. Pass the live `booking` object to `bookInsurance` instead of passing
+   `bookingNumber` and `guestToken`.
+6. Keep the booking object in memory until optional v9 insurance booking is
+   complete; private credentials do not survive JSON serialization.
+
+The search capability API is additive. Consumers with hardcoded backend period-key
+tables can replace them with the new helpers.
+
+See `versions/2.13.0/MIGRATION.md`, `../../search.md`, `../../booking.md`, and
+`../../quote.md`.