@v-office/website-sdk 2.11.0 → 2.13.0

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 `?`.
@@ -87,17 +109,38 @@ Use `&` to combine period, occupancy, and filter parameters:
 "start=20-06-2026&end=27-06-2026&adults=2&wifi";
 ```
 
+### Empty Queries
+
+On v9, an empty query returns the first page of searchable inventory under the
+configured rental scope:
+
+```ts
+await sdk.live.search.search({
+  locale: "de-DE",
+  query: "",
+});
+```
+
+The v9 facade serializes an empty backend-filter set as GraphQL `data: null`.
+Pagination and the configured `limit` still apply; an undated query does not
+assert availability for a particular stay.
+
 ### Period Queries
 
 Use one supported period structure per query.
 
-Exact period search:
+Fixed-period search is supported by both v9 and v10:
 
 ```ts
 "start=20-06-2026&end=27-06-2026";
 ```
 
-Flexible search by month:
+Flexible-period search is supported by v10 only. Legacy v9 rejects the `month`,
+`dates`, `nights`, and `weekend` keys before transport instead of silently
+returning an unpriced item list. Keep the flexible selector unavailable on v9
+sites and use `start` plus `end` for a fixed-period search.
+
+Flexible v10 search by month:
 
 ```ts
 "month=06-2026&nights=7";
@@ -106,7 +149,7 @@ Flexible search by month:
 "month=06-2026&month=07-2026&weekend";
 ```
 
-Flexible search by exact date tuples:
+Flexible v10 search by exact date tuples:
 
 ```ts
 "dates=20-06-2026,22-06-2026&nights=2";
@@ -134,6 +177,9 @@ Boolean filters can be provided as presence-only flags when supported:
 
 ### Invalid Combinations
 
+The following flexible-query validation rules apply to v10. Legacy v9 rejects
+every flexible-period key as described above.
+
 Do not mix exact period search with flexible period options:
 
 ```ts
@@ -155,7 +201,7 @@ Flexible queries require either `nights` or `weekend`, but not both:
 "month=06-2026&nights=7&weekend";
 ```
 
-Dates should use `DD-MM-YYYY`; months should use `MM-YYYY`.
+Flexible date tuples accept `DD-MM-YYYY` and `YYYY-MM-DD`; months use `MM-YYYY`.
 
 Use `rentalIdsIn` to restrict results to specific rental IDs. This option is currently supported by `v10` only.
 Use `voucher` to price v10 search results with a voucher code. This option is currently supported by `v10` only.
@@ -349,17 +395,58 @@ the expanded leaf entries. A UI may collapse those leaves under the composition
 display, but should keep the returned keys and canonical values when removing direct
 filters.
 
-## v10 Backend
+## Backend Behavior
+
+### v10
 
-v10 search runs against the dedicated REST search backend (`POST` to the configured `searchEndpoint`). Existing calls and the output type remain compatible, while the input additionally supports optional sorting. v10 results reflect the REST projection:
+v10 search runs against the dedicated REST search backend (`POST` to the configured
+`searchEndpoint`). Existing calls and the output type remain compatible, while the
+input additionally supports optional sorting. v10 results reflect the REST
+projection:
 
 - At most five images per item, and no image `category`.
-- `property` is the minimal `{ id, nameOrLabel }` shape. Hydrate `property.location`, `property.images`, or `property.address` from `sdk.static.rentals.getRentals(...)` when a card needs them.
-- Custom-attribute search filters and highlights require the `customAttributes` registry. A definition with no catalog ID cannot be executed, so its query key is left in `unusedFilterKeys`. v9 never executes a custom-attribute filter at all. See `custom-attributes.md`.
-- Fixed-period and flexible searches are priced by the REST backend and require occupancy.
-- Priced items and alternative periods may include localized `discount` details when the REST backend returns them. Legacy v9 search does not populate this field.
-- Search inputs are unchanged. The SDK keeps alternative-cancellation-policy pricing out of search; cancellation-policy selection remains part of the quote and booking flow.
-- Pagination uses the backend `from`/`size` window behind the same opaque `cursor`, capped at 1,000 results.
+- `property` is the minimal `{ id, nameOrLabel }` shape. Hydrate
+  `property.location`, `property.images`, or `property.address` from
+  `sdk.static.rentals.getRentals(...)` when a card needs them.
+- Custom-attribute search filters and highlights require the `customAttributes`
+  registry. A definition with no catalog ID cannot be executed, so its query key
+  is left in `unusedFilterKeys`. See `custom-attributes.md`.
+- Fixed-period and flexible searches are priced by the REST backend and require
+  occupancy.
+- Priced items and alternative periods may include localized `discount` details
+  with multiple applied modifiers when the REST backend returns them.
+- The v10 public search input shape is unchanged. The SDK keeps
+  alternative-cancellation-policy
+  pricing out of search; cancellation-policy selection remains part of the quote
+  and booking flow.
+- Pagination uses the backend `from`/`size` window behind the same opaque `cursor`,
+  capped at 1,000 results.
+
+### Legacy v9
+
+Legacy v9 maps its aggregated search calculation into the shared price and discount
+shape:
+
+- Flexible-period keys (`month`, `dates`, `nights`, and `weekend`) are rejected
+  before transport. v9 sites must use a fixed `start`/`end` period.
+- Empty basic-filter sets are sent as GraphQL `data: null`, allowing an empty
+  query to browse the scoped searchable inventory without a dummy occupancy
+  value.
+- `calc.total` becomes `formattedTotal`.
+- `discount` is included only when `calc.oTotal` is greater than `calc.total`.
+- `calc.oTotal` becomes `discount.formattedOriginalTotal`.
+- A non-empty `calc.discountName` becomes the label of the single `applied` entry.
+- The applied amount is the formatted negative difference
+  `calc.total - calc.oTotal`.
+- Missing discount names produce an empty `applied` array without discarding the
+  formatted original total.
+- The same mapping applies to exact-period items and individual alternative
+  periods.
+- v9 never executes a custom-attribute search filter.
+
+The field is omitted when v9 returns no final total or when its original total is
+not greater than the final total. v9 exposes at most one aggregated applied entry,
+whereas v10 can expose multiple detailed modifiers.
 
 ## Configuration
 

package/instructions/versions/2.12.0/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog: 2.12.0
+
+This release extends the optional search discount output introduced in 2.11.0 to
+legacy v9 search results, keeps zero-value lines out of quote booking-card
+breakdowns, and completes v10 card-level pre-modifier totals across all modifier
+presentation paths. It also rejects unsupported v9 flexible-period searches before
+transport and restores empty-query inventory browsing on v9.
+
+## Added
+
+- Priced legacy v9 exact-period items may include the shared optional `discount`
+  output.
+- Individual legacy v9 alternative periods expose the same optional discount
+  shape.
+- v9 maps its aggregated original total and discount name into
+  `formattedOriginalTotal` and at most one localized `applied` entry.
+
+## Changed
+
+- Legacy v9 search now rejects the unsupported flexible-period query keys
+  `month`, `dates`, `nights`, and `weekend` before transport instead of silently
+  returning an unpriced item list. Fixed `start`/`end` searches are unchanged.
+- Legacy v9 search serializes an empty backend-filter set as GraphQL `data: null`
+  instead of `data: []`. Empty queries can therefore browse searchable inventory
+  without seeding a dummy occupancy value.
+- When a v9 discount is present, `formattedTotal` remains the final price and the
+  applied amount is the formatted difference from the original total.
+- v10 search discount behavior is unchanged from 2.11.0 and can continue to expose
+  multiple applied modifiers.
+- Quote booking cards now omit zero-value lines without subitems from the `other`
+  section on both v10 and legacy v9, matching the existing empty-line behavior of
+  the included and tax sections.
+- If an `other` section contains both zero-value and non-zero lines, only the
+  non-zero lines remain. The section is omitted when no lines remain.
+- v10 derives card-level `totalBeforeModifiers` from all backend modifiers,
+  including negative modifiers rendered as dedicated booking-card lines.
+- Booking-card items omit the optional `modifiers` field when no modifier entries
+  are present instead of producing `modifiers: []`.
+
+## Migration Impact
+
+- Existing supported search calls require no changes because `discount` remains
+  optional. v9 sites must keep flexible search unavailable and use `start`/`end`
+  period queries.
+- v9 sites that inject `adults=1` only to make an empty query return results
+  should remove that workaround. Real occupancy filters remain supported.
+- Search configuration, the public input type, and the discount schema are
+  unchanged. Runtime validation is stricter for unsupported v9 flexible-period
+  keys.
+- Cross-backend sites can use one discount renderer for v9 and v10, while allowing
+  v9 to return at most one applied entry.
+- Quote inputs and booking-card types are unchanged. Consumers may receive fewer
+  booking-card lines and may now receive the existing optional card-level
+  `totalBeforeModifiers` in additional v10 modifier cases. Do not rely on
+  zero-value rows to represent declined services.
+- See `versions/2.12.0/MIGRATION.md`, `../../search.md`, and `../../quote.md`.

package/instructions/versions/2.12.0/MIGRATION.md

@@ -0,0 +1,194 @@
+# Migration: 2.11.0 to 2.12.0
+
+2.12.0 adds optional discount information to priced legacy v9 search results,
+normalizes empty quote booking-card lines across v9 and v10, and completes v10
+card-level pre-modifier totals across all modifier presentation paths. It also
+rejects unsupported v9 flexible-period searches before transport and restores
+empty-query inventory browsing on v9. Existing supported calls remain valid
+without changes.
+
+## 1. Reuse the Shared Discount Output
+
+Legacy v9 now uses the same optional shape introduced for v10 in 2.11.0:
+
+```ts
+type SearchDiscount = {
+  readonly formattedOriginalTotal: string;
+  readonly applied: readonly {
+    readonly label: string;
+    readonly formattedAmount: string;
+  }[];
+};
+```
+
+For exact-period results, read `discount` from the item:
+
+```ts
+result.items[0]?.discount;
+```
+
+For nearby suggestions, read it from the individual alternative period:
+
+```ts
+result.alternatives?.[0]?.alternativePeriods[0]?.discount;
+```
+
+## 2. Understand the Legacy v9 Mapping
+
+For priced v9 results:
+
+- `calc.total` remains the final `formattedTotal`.
+- `discount` is present only when `calc.oTotal` is greater than `calc.total`.
+- `discount.formattedOriginalTotal` is formatted from `calc.oTotal`.
+- A non-empty `calc.discountName` becomes the label of the single applied entry.
+- The applied amount is the formatted negative difference
+  `calc.total - calc.oTotal`.
+- If the backend supplies no usable discount name, `applied` is empty while the
+  formatted original total remains available.
+
+The SDK omits `discount` when there is no final total or when the original total is
+not greater than the final total.
+
+## 3. Account for Backend Detail Differences
+
+v9 exposes one aggregated discount name and therefore returns at most one
+`discount.applied` entry. v10 search can expose multiple `discount.applied`
+entries. Consumers should render the array without assuming a fixed length.
+
+Both backends return presentation-ready localized strings. Backend numeric amounts
+and internal modifier keys are not part of the public output.
+
+## 4. Account for Booking-Card Cleanup
+
+Quote booking cards on both backends now omit numeric zero-value lines without
+subitems from the `other` section, matching the existing handling of included and
+tax sections.
+
+- A zero-only `other` section is omitted.
+- A mixed `other` section retains its non-zero lines unchanged.
+- Lines with subitems remain available because they still carry descriptive
+  content.
+
+No required booking-card property was added and the public schema remains
+source-compatible. Runtime output can contain fewer empty rows. Sites that used a
+zero-value row to represent a declined service should use explicit selection or
+service state instead of inferring that state from the price breakdown.
+
+## 5. Render v10 Quote Modifiers
+
+On v10, an item at `bookingCardInformation.sections[].lines[].item` can include:
+
+```ts
+{
+  modifiers?: readonly {
+    label: string;
+    amount: string;
+  }[];
+  totalBeforeModifiers?: string;
+}
+```
+
+The card can also include `bookingCardInformation.totalBeforeModifiers`.
+`appliedCharge` and `total` are the final amounts after modifiers. The
+corresponding `totalBeforeModifiers` is the formatted amount before modifiers and
+is omitted when there is no non-zero net modifier effect. `modifiers` is omitted
+when the item has none; entries with the same localized label are grouped and
+their amounts are summed before formatting.
+
+Included, tax, and other lines attach their adjustments to `item.modifiers`.
+Negative modifiers from backend lines that do not map to those sections may
+instead appear as dedicated booking-card lines. In 2.12.0, card-level
+`totalBeforeModifiers` accounts for both forms. v9 quote cards omit these fields.
+
+Example for `de-DE`:
+
+```json
+{
+  "bookingCardInformation": {
+    "sections": [
+      {
+        "lines": [
+          {
+            "item": {
+              "position": "Inklusivpreis",
+              "appliedCharge": "1.554,00 €",
+              "modifiers": [
+                {
+                  "label": "Frühbucher/Last-Minute",
+                  "amount": "-140,00 €"
+                }
+              ],
+              "totalBeforeModifiers": "1.694,00 €"
+            }
+          }
+        ]
+      }
+    ],
+    "total": "1.596,70 €",
+    "totalBeforeModifiers": "1.736,70 €"
+  }
+}
+```
+
+Do not assume a voucher appears as its own section line. Use
+`quote.voucher.status` for voucher application status and the booking-card fields
+for price presentation. To keep price arithmetic visible, render the pre-modifier
+amount, modifier rows, and final amount separately. Whether to display or strike
+through a reference price remains the consuming site's product and legal
+decision.
+
+## 6. Keep Flexible Search Disabled on v9
+
+No configuration or supported request migration is required. Legacy v9 now rejects
+the unsupported flexible-period keys `month`, `dates`, `nights`, and `weekend`
+before transport instead of silently returning an unpriced item list. Keep
+flexible search unavailable on v9 sites and use fixed `start`/`end` period
+queries. v10 flexible search is unchanged.
+
+The rejection is a `CoreSDKError` with operation `v9.search` and occurs before a
+GraphQL request is sent. The public `SearchSearchInput` type remains unchanged
+because its `query` field is an opaque query string.
+
+This release enriches v9 search output when its existing response contains
+sufficient discount data, removes empty quote breakdown rows from both backends,
+and can return the existing optional card-level `totalBeforeModifiers` in
+additional v10 cases.
+
+## 7. Remove Dummy Occupancy from Empty v9 Searches
+
+Legacy v9 now sends an empty backend-filter set as GraphQL `data: null` instead of
+`data: []`. An empty query can therefore browse the first page of searchable
+inventory under the configured rental scope:
+
+```ts
+await sdk.live.search.search({
+  locale: "de-DE",
+  query: "",
+});
+```
+
+Remove workarounds that inject `adults=1` only to make an empty query return
+results. Real occupancy, period, and non-empty backend filters keep their existing
+mapping. Pagination and `limit` still apply, and an undated result does not assert
+availability for a particular stay.
+
+## Recommended Verification
+
+1. Run a priced v9 exact-period search where the original total exceeds the final
+   total and verify the formatted values and label.
+2. Verify discounted v9 alternative periods independently.
+3. Run a v9 search without a discount and confirm existing rendering is unchanged.
+4. Verify a missing v9 discount name produces an empty `applied` array.
+5. Verify v9 rejects `month`, `dates`, `nights`, and `weekend` before transport.
+6. Run an empty v9 query and confirm it returns searchable inventory without a
+   dummy occupancy value.
+7. Recheck a discounted v10 search and confirm its existing multi-entry behavior
+   remains unchanged.
+8. Quote a v9 and v10 rental with a zero-value `other` service and confirm the
+   empty section is absent.
+9. Confirm a mixed `other` section retains only its non-zero lines.
+10. Quote a discounted v10 rental and render `item.modifiers`, item-level
+    `totalBeforeModifiers`, and card-level `totalBeforeModifiers`.
+11. Confirm a v9 quote continues to omit the modifier fields.
+12. Verify a v10 modifier rendered as a dedicated line still contributes to the
+    card-level `totalBeforeModifiers`.

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`.