@v-office/website-sdk 2.10.0 → 2.12.0

package/instructions/search.md

@@ -87,17 +87,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 +127,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 +155,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 +179,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.
@@ -227,6 +251,18 @@ The supported fields are `label`, `name`, all six `roomSummary` counters, `attri
 
 Returns `Promise<RentalSearchOutput>`.
 
+Priced items and alternative periods share this optional discount shape:
+
+```ts
+type SearchDiscount = {
+  readonly formattedOriginalTotal: string;
+  readonly applied: readonly {
+    readonly label: string;
+    readonly formattedAmount: string;
+  }[];
+};
+```
+
 Sample:
 
 ```json
@@ -250,7 +286,16 @@ Sample:
         }
       ],
       "highlights": ["2 bedrooms", "WiFi", "Parking"],
-      "formattedTotal": "1.234,00 €"
+      "formattedTotal": "1.111,00 €",
+      "discount": {
+        "formattedOriginalTotal": "1.234,00 €",
+        "applied": [
+          {
+            "label": "Frühbucher-Rabatt",
+            "formattedAmount": "-123,00 €"
+          }
+        ]
+      }
     }
   ],
   "alternatives": [
@@ -264,7 +309,16 @@ Sample:
         {
           "start": "2026-07-10",
           "end": "2026-07-17",
-          "formattedTotal": "1.456,00 €"
+          "formattedTotal": "1.310,00 €",
+          "discount": {
+            "formattedOriginalTotal": "1.456,00 €",
+            "applied": [
+              {
+                "label": "Frühbucher-Rabatt",
+                "formattedAmount": "-146,00 €"
+              }
+            ]
+          }
         }
       ]
     }
@@ -288,7 +342,15 @@ Sample:
 }
 ```
 
-Search items share the rental base fields and may include `scope`, `address`, `property`, `highlights`, and `formattedTotal`. Exact-period results are returned in `items`; alternative-period suggestions are returned in root-level `alternatives`.
+Search items share the rental base fields and may include `scope`, `address`,
+`property`, `highlights`, and `formattedTotal`. A priced item or alternative period
+may also include `discount`. When it does, `formattedTotal` is the final price and
+`discount.formattedOriginalTotal` is the price before the applied discounts.
+Discount totals, labels, and amounts are already localized and formatted for the
+requested locale; backend numeric amounts and modifier type keys are not exposed.
+`applied` may be empty when the backend supplies an original total without
+individual modifier lines. Exact-period results are returned in `items`;
+alternative-period suggestions are returned in root-level `alternatives`.
 
 `appliedFilters` reports what the backend actually applied, and is what a "remove
 this filter" chip should be built from. `label` is localized presentation and can
@@ -311,15 +373,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.
-- 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.11.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog: 2.11.0
+
+This release exposes localized v10 REST search discount details on priced search
+results.
+
+## Added
+
+- Priced v10 search items may include an optional `discount` with the localized
+  pre-discount total in `formattedOriginalTotal`.
+- `discount.applied` lists each applied discount as a localized `label` and
+  `formattedAmount`.
+- Alternative-period suggestions expose the same optional discount shape on each
+  priced period.
+
+## Changed
+
+- When `discount` is present, `formattedTotal` remains the final price after the
+  listed discounts.
+- Backend modifier types and numeric amounts remain internal; the public search
+  output contains presentation-ready localized strings.
+
+## Migration Impact
+
+- Existing search calls require no changes because `discount` is optional.
+- Search configuration and input are unchanged.
+- Legacy v9 search does not populate `discount`.
+- Sites can opt in to strike-through pricing and discount labels by reading the
+  new field. See `versions/2.11.0/MIGRATION.md` and `../../search.md`.

package/instructions/versions/2.11.0/MIGRATION.md

@@ -0,0 +1,72 @@
+# Migration: 2.10.0 to 2.11.0
+
+2.11.0 adds optional localized discount information to priced v10 search results.
+Existing search calls and rendering remain valid without changes.
+
+## 1. Read the Optional Discount
+
+Exact-period items and individual alternative periods may now include:
+
+```ts
+type SearchDiscount = {
+  readonly formattedOriginalTotal: string;
+  readonly applied: readonly {
+    readonly label: string;
+    readonly formattedAmount: string;
+  }[];
+};
+```
+
+The field is omitted when the REST search backend returns no discount. Keep
+rendering `formattedTotal` as before and add discount presentation only when
+`discount` is present.
+
+## 2. Distinguish Final and Original Totals
+
+When a discount is present:
+
+- `formattedTotal` is the final price after the applied discounts.
+- `discount.formattedOriginalTotal` is the total before those discounts.
+- `discount.applied` contains presentation-ready localized labels and formatted
+  amounts.
+
+All monetary values already include locale-aware currency formatting. Backend
+numeric amounts and modifier type keys are intentionally not exposed.
+
+## 3. Handle Exact and Alternative Periods
+
+For a fixed-period match, read the field from the item:
+
+```ts
+result.items[0]?.discount;
+```
+
+For a nearby-period suggestion, read it from the individual period:
+
+```ts
+result.alternatives?.[0]?.alternativePeriods[0]?.discount;
+```
+
+Each alternative period has independent pricing and may have a different discount
+or no discount.
+
+## 4. Keep Search Inputs Unchanged
+
+No configuration or input migration is required. The SDK continues to request the
+existing default v10 search pricing and does not opt search into alternative
+cancellation-policy pricing.
+
+Legacy v9 search does not populate `discount`; consumers supporting both backends
+must treat it as optional.
+
+## Recommended Verification
+
+1. Run a priced v10 exact-period search that has a configured discount and verify
+   the final and original totals.
+2. Verify each applied entry has a localized label and formatted amount in every
+   supported locale.
+3. Run a priced search without a discount and confirm existing rendering is
+   unchanged.
+4. Check nearby alternative periods independently because discounts can differ by
+   period.
+5. If the site supports v9, confirm its existing search output remains unchanged.

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.5.0/MIGRATION.md

@@ -121,6 +121,12 @@ The public output type is unchanged, but v10 search cards now reflect the REST p
 - `property` is the minimal `{ id, nameOrLabel }` shape. Hydrate `property.location`, `property.images`, or `property.address` from `sdk.static.rentals.getRentals(...)` when a search card needs them.
 - Exact-period matches are returned in `items` with `formattedTotal`; nearby suggestions are returned in root-level `alternatives`, unchanged.
 
+Starting with 2.11.0, priced v10 items and alternative periods may also include
+optional localized `discount` details. See `../../search.md`.
+
+Starting with 2.12.0, legacy v9 maps the same optional shape from its aggregated
+original total and discount name when the original total exceeds the final total.
+
 ## Backend Behavior
 
 - Fixed-period and flexible searches are priced by the REST backend; occupancy is required for priced searches.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v-office/website-sdk",
-  "version": "2.10.0",
+  "version": "2.12.0",
   "description": "Website-facing SDK facade backed by @v-office/sdk-core",
   "bin": {
     "website-sdk": "./dist/cli.mjs"
@@ -41,21 +41,23 @@
   },
   "dependencies": {
     "@graphql-typed-document-node/core": "3.2.0",
-    "@v-office/sdk-core": "^1.10.0",
+    "@v-office/sdk-core": "^1.12.0",
     "effect": "4.0.0-beta.85",
-    "graphql": "16.14.2",
+    "graphql": "17.0.2",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@effect/language-service": "0.86.2",
-    "@graphql-codegen/cli": "7.1.3",
-    "@graphql-codegen/client-preset": "6.0.1",
-    "@types/node": "26.0.0",
-    "@typescript/native-preview": "7.0.0-dev.20260622.1",
-    "oxfmt": "0.55.0",
-    "oxlint": "1.70.0",
-    "tsdown": "0.22.3",
-    "typescript": "6.0.3"
+    "@effect/tsgo": "0.31.0",
+    "@graphql-codegen/cli": "7.2.0",
+    "@graphql-codegen/client-preset": "6.1.1",
+    "@types/node": "26.1.2",
+    "oxfmt": "0.62.0",
+    "oxlint": "1.77.0",
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2"
+  },
+  "engines": {
+    "node": "^22.0.0 || ^24.0.0 || ^25.0.0 || >=26.0.0"
   },
   "scripts": {
     "p": "pnpm run playground:json",
@@ -72,7 +74,7 @@
     "lint:fix": "oxlint --fix .",
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check",
-    "check": "pnpm run typecheck && pnpm run lint",
+    "check": "pnpm run typecheck && pnpm run lint && pnpm run fmt:check",
     "test": "pnpm run build && node --test test/*.test.mjs",
     "playground:custom-attributes": "pnpm run build && node --env-file=.env playground/custom-attributes.ts"
   }