@v-office/website-sdk 2.17.1 → 2.18.0

package/instructions/CHANGELOG.md

@@ -4,6 +4,7 @@ This file is the versioned changelog index for the website SDK instructions.
 
 ## Versions
 
+- `versions/2.18.0/CHANGELOG.md`: `@v-office/website-sdk` 2.18.0 release notes.
 - `versions/2.17.1/CHANGELOG.md`: `@v-office/website-sdk` 2.17.1 release notes.
 - `versions/2.17.0/CHANGELOG.md`: `@v-office/website-sdk` 2.17.0 release notes.
 - `versions/2.16.3/CHANGELOG.md`: `@v-office/website-sdk` 2.16.3 release notes.

package/instructions/MIGRATION.md

@@ -4,6 +4,7 @@ This file is the versioned migration index for the website SDK instructions.
 
 ## Available Guides
 
+- `versions/2.18.0/MIGRATION.md`: migrate from `@v-office/website-sdk` 2.17.1 to 2.18.0.
 - `versions/2.17.1/MIGRATION.md`: migrate from `@v-office/website-sdk` 2.17.0 to 2.17.1.
 - `versions/2.17.0/MIGRATION.md`: migrate from `@v-office/website-sdk` 2.16.3 to 2.17.0.
 - `versions/2.16.3/MIGRATION.md`: migrate from `@v-office/website-sdk` 2.16.2 to 2.16.3.

package/instructions/README.md

@@ -1,7 +1,7 @@
 # Website SDK Instructions
 
 These instructions describe the current source targeted for
-`@v-office/website-sdk` 2.17.1. Package versions remain unchanged until the release
+`@v-office/website-sdk` 2.18.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,11 @@ 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.18.0/`: 2.18.0 opt-in legacy-v9 facility association through
+  facility custom attributes and vOffice object groups, configurable v9
+  facility `p_*` line-list highlights, initial-availability prices on available
+  non-start dates, combined seasonal rent rows on quote booking cards, and the
+  2.17.1-to-2.18.0 migration guide.
 - `versions/2.17.1/`: 2.17.1 legacy-v9 EUR fallback for calendar prices when
   unit currency metadata is unavailable, and the 2.17.0-to-2.17.1 migration
   guide.
@@ -107,5 +112,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.17.1. v10 config additionally requires `searchEndpoint` as
+in 2.0.0 and kept in 2.18.0. v10 config additionally requires `searchEndpoint` as
 of 2.5.0.

package/instructions/availability.md

@@ -61,9 +61,9 @@ Initial availability returns `Promise<InitialAvailabilityOutput>`.
     },
     "2026-07-02": {
       "canBeStartDate": false,
-      "isAvailableDate": false,
+      "isAvailableDate": true,
       "status": "check_in_not_allowed",
-      "formattedPrice": null,
+      "formattedPrice": "120.00 EUR",
       "tooltip": "Arrival is not possible on this date."
     }
   },
@@ -99,12 +99,14 @@ Common statuses include `available`, `before_today`, `check_in_not_allowed`, `no
 ### Legacy v9 Calendar-Day Prices
 
 From 2.17.0, v9 initial availability uses the numeric price supplied by the v1
-calendar to populate `formattedPrice` on valid start dates. The value is already
+calendar to populate `formattedPrice` on available dates. The value is already
 localized and formatted in the rental unit's configured booking currency.
 Render it directly rather than parsing or reformatting it.
 
-`formattedPrice` remains `null` when the date cannot be used as a start date,
-the date is unavailable, or the v1 calendar supplies no numeric price.
+From 2.18.0, available dates that cannot be used as a start date also expose a
+price when the source supplies one. The same rule applies to v10 initial
+availability. `formattedPrice` remains `null` when the date is unavailable or
+the source supplies no numeric price.
 Start-date-selected availability does not include calendar prices.
 
 When no successful unit lookup is cached, a v9 initial-availability request loads
@@ -117,8 +119,8 @@ calendar prices fall back to `EUR`.
 No new configuration is required. The currency lookup uses the existing
 `v1ApiBaseUrl` and `apiKey`.
 
-See `versions/2.17.1/CHANGELOG.md` and
-`versions/2.17.1/MIGRATION.md`.
+See `versions/2.18.0/CHANGELOG.md` and
+`versions/2.18.0/MIGRATION.md`.
 
 ## Configuration
 

package/instructions/creation.md

@@ -48,10 +48,21 @@ const sdk = createWebsiteSDK({
     apiKey: "...",
     imageProxyBaseUrl: "https://images.example.com",
     rentalDataAttributes: ["name", "description"],
+    facilityObjectGroupRelationAttributeId: 18962,
   },
 });
 ```
 
+`facilityObjectGroupRelationAttributeId` is an optional v9-only compatibility
+setting for tenants whose units are associated with facilities through vOffice
+object groups instead of the native facility relation. Its numeric value `N`
+selects the facility data attribute `p_N`. The attribute must contain one or
+more object-group IDs. When omitted, the SDK continues to use each unit's
+native `voffice_facility` relation.
+
+See `versions/2.18.0/CHANGELOG.md`, `versions/2.18.0/MIGRATION.md`, and
+`rentals.md`.
+
 `v10`:
 
 ```ts
@@ -93,6 +104,7 @@ const options = defineWebsiteSDKOptions({
 type WebsiteSDKOptions = {
   translationOverrides?: TranslationOverrides;
   customAttributes?: CustomAttributeRegistrySnapshot;
+  v9PropertyHighlightSources?: V9PropertyHighlightSourceRegistry;
   customAttributeFilterDefinitions?: readonly CustomAttributeFilterDefinition[];
   rentalHighlightPrioritization?: readonly RentalHighlightPrioritizationKey[];
   rentalPropertyHighlightPrioritization?: readonly RentalPropertyHighlightPrioritizationKey[];
@@ -105,7 +117,8 @@ type WebsiteSDKOptions = {
 which facts become highlights and set their order. They are ordered allowlists, not
 sorts over every available fact. A key that is not listed is not emitted even when
 the source contains a value. This affects `highlights` only, not `attributes` or
-`vicinity`. Property highlights are available only with v10 property data.
+`vicinity`. v10 uses its property metadata catalog. v9 supports its built-in
+facility fields and configured `p_*` line-list sources.
 
 For either option, `undefined` uses the SDK default and `[]` emits no highlights.
 Duplicate keys are emitted once; unknown, unsupported, or unresolved keys are
@@ -116,6 +129,7 @@ not part of this strongest-view selection.
 Unset options are normalized by the SDK:
 
 - `customAttributes` defaults to an empty registry.
+- `v9PropertyHighlightSources` defaults to an empty registry.
 - `customAttributeFilterDefinitions` defaults to `[]`.
 - `rentalHighlightPrioritization` defaults to the SDK default rental highlight selection.
 - `rentalPropertyHighlightPrioritization` defaults to the SDK default property highlight selection.
@@ -123,6 +137,37 @@ Unset options are normalized by the SDK:
 - `shouldAddProposedAdditionalServiceAmount` defaults to `false`.
 - `translationOverrides` is omitted unless provided.
 
+### v9 Property Highlight Sources
+
+Use `defineV9PropertyHighlightSources` when a tenant stores facility highlights
+as newline-separated text in a custom facility field:
+
+```ts
+import { defineV9PropertyHighlightSources, defineWebsiteSDKOptions } from "@v-office/website-sdk";
+
+const v9PropertyHighlightSources = defineV9PropertyHighlightSources({
+  facilityHighlights: {
+    v9: "p_18963",
+    type: "line-list",
+  },
+});
+
+const options = defineWebsiteSDKOptions({
+  v9PropertyHighlightSources,
+  rentalPropertyHighlightPrioritization: [
+    "childrenWelcome",
+    v9PropertyHighlightSources.keys.facilityHighlights,
+    "pets",
+  ],
+});
+```
+
+The source is v9-only and affects the existing `property.highlights` array.
+Its field is requested only when the stable source key is selected. Newlines
+separate highlights; surrounding whitespace, empty lines, and duplicate visible
+values are removed. Missing values are ignored. Rental custom attributes remain
+independent and do not feed property highlights.
+
 ## Rental Scope
 
 Use `rentalScope` to restrict all rental lists and searches created by this SDK instance:

package/instructions/custom-attributes.md

@@ -303,6 +303,13 @@ value is absent — custom attributes are strictly a fallback there.
 `getRentals` renders custom attributes into both `attributes` and `highlights`;
 `search` renders them into `highlights` only.
 
+These custom attributes belong to rentals, not facilities. From 2.18.0,
+newline-separated facility `p_*` text can feed `property.highlights` through
+the separate `defineV9PropertyHighlightSources` registry and
+`v9PropertyHighlightSources` option. It is selected with
+`rentalPropertyHighlightPrioritization`; see `rentals.md`. It does not add the
+text to property `attributes` or make it searchable.
+
 In `attributes`, a custom attribute is placed in the group named by its resolved
 `category`, alongside built-in attributes of that category rather than in a separate
 bucket. The default `OTHER` therefore groups everything you did not categorize

package/instructions/quote.md

@@ -181,6 +181,14 @@ A zero-total line with subitems can remain because those subitems carry
 descriptive content. Do not use the absence or presence of a zero-value price row
 as service-selection state; use the quote's explicit service or selection data.
 
+From 2.18.0, included-section subitems that share the same localized `position`
+and the same `appliedCharge` are combined into one row. A stay that crosses
+seasonal rental rates therefore shows a single rent line instead of repeating
+the same included rent row once per season. Lines with different labels, such
+as cleaning or booking fees, stay separate. The inclusive total is unchanged.
+
+See `versions/2.18.0/CHANGELOG.md` and `versions/2.18.0/MIGRATION.md`.
+
 ### Modifiers and Pre-Modifier Totals
 
 On `v10`, a booking-card item at

package/instructions/rentals.md

@@ -123,6 +123,113 @@ list.
 
 See `versions/2.15.0/CHANGELOG.md` and `versions/2.15.0/MIGRATION.md`.
 
+### Legacy v9 Facility Details
+
+From 2.18.0, v9 static rentals populate additional fields on the existing
+`property` object when facility data is available:
+
+- `propertyType` from the v9 facility `type`
+- `location` from the GeoJSON `loc`
+- `address`, including localized `regionName` as `province`
+- localized `intro`, `headline`, `description`, `altDescription`,
+  `arrivalInfo`, `departureInfo`, `locationDescription`, and `directions`
+- built-in `attributes` for allergy suitability, children, pets, and youth
+  groups
+
+`HOUSE_FAC` and `FLAT_FAC` normalize to `HOLIDAY_HOME_COMPLEX` and
+`APARTMENT_COMPLEX`. The normalized value is localized through
+`Property.propertyType.option.*`; for example, `HOLIDAY_HOME_COMPLEX` is
+returned as `Ferienpark` for `de-DE`. Unknown types and malformed optional data
+are omitted. This fills the existing property schema and does not add public
+fields.
+
+The same parser is used for native and object-group facility relations.
+
+Use `rentalPropertyHighlightPrioritization` to select and order v9 facility
+highlights. The supported v9 keys are `allergic`, `childrenWelcome`, `pets`, and
+`youthgroups`. Unsupported, duplicate, missing, and non-renderable selections
+are ignored.
+
+Tenant-specific facility highlight text can be added without treating it as a
+rental custom attribute:
+
+```ts
+import { defineV9PropertyHighlightSources } from "@v-office/website-sdk";
+
+const v9PropertyHighlightSources = defineV9PropertyHighlightSources({
+  facilityHighlights: {
+    v9: "p_18963",
+    type: "line-list",
+  },
+});
+
+const options = {
+  v9PropertyHighlightSources,
+  rentalPropertyHighlightPrioritization: [
+    "childrenWelcome",
+    v9PropertyHighlightSources.keys.facilityHighlights,
+    "pets",
+  ],
+};
+```
+
+The selected field is fetched with facility data for both native and
+object-group relations. A localized `line-list` value is split on Unix or
+Windows newlines. Lines are trimmed, blank and duplicate values are removed,
+and the remainder expands at the selected key's position. A missing or `null`
+field emits nothing. Defining but not selecting a source does not request it.
+Use one highlight per line; semicolons are not separators.
+
+### Legacy v9 Facility Relations Through Object Groups
+
+Some v9 tenants store a facility-to-object-group relation in a facility custom
+data attribute instead of assigning the facility directly to each unit. Enable
+that compatibility mode on the v9 config:
+
+```ts
+const sdk = createWebsiteSDK({
+  config: {
+    backend: "v9",
+    graphqlUrl: "https://example.com/graphql",
+    apiKey: "...",
+    imageProxyBaseUrl: "https://images.example.com",
+    facilityObjectGroupRelationAttributeId: 18962,
+  },
+});
+```
+
+The numeric value selects `p_18962`. The SDK loads facilities once and unit
+details in bounded GraphQL batches, associates units whose
+`voffice_groups[].voffice_group_id` occurs in the facility attribute, and emits
+the resolved facility through the existing `rental.property` field.
+
+This mode replaces the native v9 facility association for static rentals. It
+does not fall back to `voffice_facility` per unit and it does not change live
+search. Units with no matching object group omit `property`. Invalid relation
+values, relations claimed by several facilities, and units resolving to
+several facilities fail the static rentals request instead of selecting an
+arbitrary property. The request also fails when no facility has a usable
+configured relation value.
+
+The relation attribute may contain positive numeric IDs as numbers, strings,
+localized string records, arrays, or strings separated by whitespace, commas,
+or semicolons. The association is locale-independent. The configured GraphQL
+Hub must expose `voffice_facilities` and must have synchronized both the
+facility relation attribute and unit group memberships.
+
+See `versions/2.18.0/CHANGELOG.md` and `versions/2.18.0/MIGRATION.md`.
+
+### Legacy v9 Large Catalogue Batching
+
+From 2.18.0, v9 static rentals first load the ordered rental IDs. Complete
+rental details and feedbacks are then fetched sequentially in batches of 128
+IDs. This bounds the amount of data the Laravel/PHP Hub must construct in one
+request while preserving the existing result and rental order.
+
+Object-group facility mode loads the facility list once. Applications that mock
+or count GraphQL requests must allow multiple detail and feedback requests for
+catalogues larger than 128 rentals.
+
 ### Structured Bed Quantities
 
 From 2.17.0, both backends expand each source bed according to its `amount`.
@@ -292,8 +399,10 @@ Optional `WebsiteSDKOptions`:
 `rentalHighlightPrioritization` selects which facts become rental `highlights` and
 sets their order. It is an ordered allowlist, not a sort over every available fact.
 A key that is not listed is not emitted even when the source contains a value.
-`rentalPropertyHighlightPrioritization` has the same semantics for v10 property
-highlights. Both options affect `highlights` only, not `attributes` or `vicinity`.
+`rentalPropertyHighlightPrioritization` has the same semantics for property
+highlights. v9 supports its typed built-in facility fields and configured
+line-list sources; v10 uses its property metadata catalog. Both options affect
+`highlights` only, not `attributes` or `vicinity`.
 
 For either option, `undefined` uses the SDK default and `[]` emits no highlights.
 Duplicate keys are emitted once; unknown, unsupported, or unresolved keys are
@@ -312,6 +421,25 @@ In CLI JSON, `customAttributes` contains catalog and selection inputs; the CLI b
 the validated registry. Typed applications normally call `defineCustomAttributes`
 and pass its result instead.
 
+The same authored-input rule applies to v9 property highlight sources. A v9 CLI
+options file can contain:
+
+```json
+{
+  "v9PropertyHighlightSources": {
+    "facilityHighlights": {
+      "v9": "p_18963",
+      "type": "line-list"
+    }
+  },
+  "rentalPropertyHighlightPrioritization": ["childrenWelcome", "facilityHighlights", "pets"]
+}
+```
+
+The CLI validates the stable key, positive-integer `p_*` binding, `line-list`
+type, binding uniqueness, and collisions with built-in v9 facility highlight
+keys before SDK creation.
+
 Custom attributes configured through `customAttributes` add values to rental output on
 both backends. A value appears in `highlights` only when its key is listed in
 `rentalHighlightPrioritization`, and in `attributes` under the group named by its

package/instructions/versions/2.18.0/CHANGELOG.md

@@ -0,0 +1,133 @@
+# Changelog: 2.18.0
+
+This release adds an opt-in legacy-v9 compatibility mode for tenants that
+associate facilities and rentals through vOffice object groups instead of the
+native unit-to-facility relation. Initial-availability calendar days also
+expose a localized `formattedPrice` on available dates that cannot be used as
+a start date. Quote booking cards also combine repeated included rent rows
+when a stay crosses seasonal rates.
+
+## Added
+
+- `WebsiteV9Config` accepts the optional positive integer
+  `facilityObjectGroupRelationAttributeId`.
+- When configured with an ID such as `18962`, legacy-v9 static rentals request
+  the facility data attribute `p_18962`.
+- The v9 static rentals GraphQL operation can load top-level facilities and
+  each unit's `voffice_groups[].voffice_group_id` in one request.
+- The SDK associates matching units with the facility and exposes it through
+  the existing optional `rental.property` field.
+- Legacy-v9 facilities populate additional existing `rental.property` fields:
+  `propertyType`, `location`, `address`, complete description components, and
+  supported built-in `attributes`.
+- Facility types are normalized to the existing property-type values and then
+  localized through `Property.propertyType.option.*`.
+- `rentalPropertyHighlightPrioritization` now selects and orders built-in v9
+  facility highlights.
+- Added `defineV9PropertyHighlightSources` and the
+  `v9PropertyHighlightSources` website option. A tenant-specific facility
+  `p_*` field can now contribute newline-separated text to the existing
+  `rental.property.highlights` array without becoming a rental custom
+  attribute.
+- Configured facility highlight fields are requested only when their stable
+  key is selected by `rentalPropertyHighlightPrioritization`. Lines are
+  trimmed, empty lines and duplicates are removed, and the remaining lines
+  expand at that key's configured position.
+- Facility relation values support positive numbers, numeric strings,
+  localized records, arrays, and strings separated by whitespace, commas, or
+  semicolons.
+
+## Changed
+
+- Legacy-v9 static rentals first load the rental IDs and then request complete
+  rental details in sequential batches of 128 IDs.
+- Legacy-v9 rental feedback requests use the same sequential 128-ID batches.
+  This limits the amount of rental data the Hub must construct and serialize in
+  one PHP request.
+- Object-group compatibility mode loads top-level facilities once instead of
+  repeating facility data for every rental-detail batch.
+- The CLI validates authored `v9PropertyHighlightSources` from the JSON options
+  file, as it already does for authored custom-attribute inputs.
+
+## Fixed
+
+- Initial availability exposes `formattedPrice` on available dates that cannot
+  be used as a start date (`check_in_not_allowed` and
+  `no_valid_check_out_from_start`) when the source supplies a numeric price.
+- Legacy-v9 uses the existing v1 calendar `price`. v10 uses the existing
+  guest-summary rent series. Both already computed that value and previously
+  returned `formattedPrice: null` on those statuses.
+- Unavailable dates and dates without a numeric source price continue to
+  return `formattedPrice: null`.
+- Quote booking cards combine included subitems that share the same localized
+  `position` and `appliedCharge` into one row on v9 and v10.
+- A stay that crosses seasonal rental prices no longer repeats the rent line
+  once per season. Distinct included labels remain separate rows. The
+  inclusive total is unchanged.
+
+## Unchanged
+
+- Omitting `facilityObjectGroupRelationAttributeId` retains the existing
+  `voffice_facility` association and existing GraphQL operation.
+- The public `getRentals` input and output types are unchanged.
+- The shared core `RentalPropertySchema` is unchanged; configured facility
+  highlight lines use its existing `highlights` field.
+- Rental and property IDs keep their existing semantics.
+- The compatibility mode affects only
+  `sdk.static.rentals.getRentals({ locale })`.
+- `sdk.live.availability.getInitialAvailability(input)` keeps its existing
+  signature and public TypeScript contract.
+- Start-date-selected availability output does not gain calendar prices.
+- Live search, booking, contact, and the shared core rental domain are
+  unchanged. Quote inputs and booking-card types are unchanged.
+- No booking or mutation request is introduced.
+
+## Validation and Failure Behavior
+
+- Configuration fails during SDK creation when the relation attribute ID is
+  zero, negative, fractional, or not a safe integer.
+- Property-highlight source definition fails for invalid stable keys, keys
+  reserved by built-in v9 facility highlights, invalid positive-integer `p_*`
+  bindings, unsupported types, or duplicate bindings.
+- The static rentals request fails when no facility has a usable configured
+  relation value.
+- The static rentals request fails when a non-empty relation value is malformed,
+  one object group is claimed by several facilities, or one rental resolves to
+  several different facilities.
+- A facility relation that references no current unit is valid.
+- Rentals without a matching configured object group remain in the result and
+  omit `property`.
+- When compatibility mode is enabled, the SDK does not fall back to the native
+  facility relation for unmatched rentals.
+
+## Compatibility
+
+- Existing v9 and v10 configurations require no changes.
+- Tenants enabling the new mode need a GraphQL Hub that exposes
+  `voffice_facilities` and synchronizes both the configured facility `p_*`
+  attribute and unit object-group memberships.
+- Complete snapshots can gain `property` on rentals that previously had no
+  native facility relation.
+- Existing v9 property snapshots can gain `propertyType`, `location`, `address`,
+  more description fields, and built-in attributes when the Hub supplies them.
+- Configuring a v9 property highlight source has no output effect until its key
+  is also selected. Once selected and synchronized in GraphQL, complete rental
+  snapshots can gain one highlight per non-empty source line.
+- Large v9 catalogues perform several bounded detail and feedback queries
+  instead of one oversized request. The returned rental order and public output
+  remain unchanged.
+- Complete initial-availability snapshots can change from
+  `formattedPrice: null` to a formatted value on available non-start dates.
+- The v10 calendar-price change is delivered through `@v-office/sdk-core`.
+  Refresh the lockfile when upgrading so the website package resolves the
+  coordinated core version shipped for 2.18.0.
+- No configuration or consumer code change is required for the calendar-price
+  change. Render `formattedPrice` directly when non-null.
+- Complete quote snapshots that listed one included rent row per seasonal
+  rate period now contain a single combined rent row. Render `subItems` as
+  returned. The v10 quote change is delivered through `@v-office/sdk-core`.
+  Refresh the lockfile when upgrading so the website package resolves the
+  coordinated core version shipped for 2.18.0.
+
+See `versions/2.18.0/MIGRATION.md`, `../../creation.md`,
+`../../rentals.md`, `../../availability.md`, and `../../quote.md`.