@v-office/website-sdk 2.7.0 → 2.9.0

package/instructions/filter.md

@@ -36,14 +36,14 @@ Sample:
 [
   {
     "searchParameterQueryKey": "wifi",
-    "label": "WiFi",
-    "category": "ESSENTIALS",
+    "label": "WLAN",
+    "category": "Grundlagen",
     "type": "BooleanFilter"
   },
   {
     "searchParameterQueryKey": "bedrooms",
-    "label": "Bedrooms",
-    "category": "ROOMS",
+    "label": "Schlafzimmer",
+    "category": "Wohn- und Schlafbereiche",
     "type": "IntFilter",
     "numericBounds": {
       "min": 1,
@@ -53,22 +53,30 @@ Sample:
   {
     "searchParameterQueryKey": "region",
     "label": "Region",
-    "category": "LOCATION",
+    "category": "Andere",
     "type": "OptionFilter",
     "options": [
       {
         "value": "north",
-        "label": "North"
+        "label": "Norden"
       }
     ]
   }
 ]
 ```
 
+`searchParameterQueryKey` and each option `value` are **stable identifiers**: they are
+what you put in a URL, and they never change with locale. `label` and `category` are
+**localized display strings** for the requested locale, not keys — do not group or
+match on them programmatically. This holds for custom attributes too: an attribute
+authored with `category: "ESSENTIALS"` is advertised with `"category": "Grundlagen"`
+in `de-DE`, exactly like a built-in filter.
+
 Filter variants:
 
 - `BooleanFilter`: on/off query parameter.
 - `IntFilter`: numeric query parameter, optionally with `numericBounds`.
+- `StringFilter`: non-empty exact-match query parameter.
 - `OptionFilter`: query parameter with localized selectable `options`.
 
 ## Configuration
@@ -85,6 +93,14 @@ Filter variants:
 }
 ```
 
+v9 has a fixed built-in filter set. These filters are always advertised, parsed,
+and usable as composition leaves; do not repeat them as `backendFilter` definitions.
+
+- Numeric: `bedrooms`, `bathrooms`.
+- Boolean: `pool`, `wifi`, `pets`, `privateparking`, `ac`, `washer`, `dishwasher`,
+  `beachfront`, `seaview`, `balcony`, `terrace`, `garden`, `bbq`, `sauna`,
+  `fireplace`, `tv`, `childrenWelcome`, `nonsmoking`, `kitchen`.
+
 `v10` config:
 
 ```json
@@ -97,29 +113,29 @@ Filter variants:
 }
 ```
 
-Optional `WebsiteSDKOptions` can add public custom filters:
+Optional `WebsiteSDKOptions` add two further sources of filters.
+
+Custom attributes come from `customAttributes`, and a definition is advertised only
+when it has a public filter and the selected backend can execute it. v9 has no
+custom-attribute search path, so v9 never advertises one; see `custom-attributes.md`.
+
+Backend filters and compositions come from `customAttributeFilterDefinitions`.
+SDK configuration cannot create a Hub filter: for another v9 key, first ask someone
+at be-on! with Hub access to add or confirm it, then configure that key as a
+`backendFilter`.
 
 ```json
 {
   "customAttributeFilterDefinitions": [
     {
-      "key": "region",
-      "source": "customAttribute",
-      "category": "ESSENTIALS",
+      "key": "atLeastTwoBedrooms",
+      "source": "backendFilter",
+      "category": "LIVING_SLEEPING",
       "label": {
-        "de-DE": "Region",
-        "en-US": "Region"
+        "de-DE": "Mind. zwei Schlafzimmer",
+        "en-US": "At least two bedrooms"
       },
-      "type": "option",
-      "options": [
-        {
-          "value": "north",
-          "label": {
-            "de-DE": "Norden",
-            "en-US": "North"
-          }
-        }
-      ],
+      "type": "boolean",
       "searchable": true,
       "internal": false
     }
@@ -128,7 +144,30 @@ Optional `WebsiteSDKOptions` can add public custom filters:
 }
 ```
 
-Only custom definitions with `searchable: true` and `internal: false` are exposed by `getFilters`.
+Only definitions with `searchable: true` and `internal: false` are exposed by
+`getFilters`. `backendFilter` entries are advertised by v9 only, because they have no
+v10 execution path. Each query key has one owner: period and occupancy collisions
+fail during option normalization, v9/v10 built-in filter collisions fail in the
+corresponding backend configuration path, and a custom attribute cannot share a key
+with a configured custom filter. Repeated keys within
+`customAttributeFilterDefinitions` also fail during option normalization.
+`getFilters` keeps a final uniqueness assertion so parse order never silently
+decides ownership.
+
+Compositions are additionally backend-aware: `getFilters` advertises one only when
+every leaf exists on the active backend and its configured value is valid for that
+leaf. Executable internal leaves may participate without being exposed separately.
+Unknown, unsupported, or backend-specific leaves omit the composition. Nested
+compositions are rejected during option normalization while recursive expansion is
+unsupported.
+
+During search, a successful composition and its expanded leaves are all returned in
+the search output's `appliedFilters`; `getFilters` itself returns only discovery
+metadata. See `search.md` for filter-chip guidance.
+
+Configured category values remain stable keys such as `OUTDOORS`. The output
+translates them through `RentalAttributesCategory.<KEY>.label`, honors
+`translationOverrides`, and returns only the localized display label.
 
 For v10, `getFilters` also exposes the mapped BooleanFilter `pets`, labeled `Dogs welcome` / `Hunde willkommen`. It maps to one pet in search occupancy; use `petsCount` when the UI needs an exact pet count instead.
 

package/instructions/rentals.md

@@ -147,14 +147,55 @@ Optional `WebsiteSDKOptions`:
 
 ```json
 {
-  "rentalHighlightPrioritization": ["bedrooms", "bathrooms", "maxPersons", "wifi"],
+  "customAttributes": {
+    "catalog": {
+      "privateSauna": {
+        "id": "GQYKYgMVh28X7VLGursbkt",
+        "type": "BOOLEAN"
+      }
+    },
+    "select": {
+      "privateSauna": {
+        "label": { "de-DE": "Sauna", "en-US": "Sauna" }
+      }
+    }
+  },
+  "rentalHighlightPrioritization": ["bedrooms", "privateSauna", "wifi"],
   "rentalPropertyHighlightPrioritization": ["wifi", "parking"],
   "customAttributeFilterDefinitions": [],
   "translationOverrides": {}
 }
 ```
 
-`rentalHighlightPrioritization` controls the order of rental `highlights`. `rentalPropertyHighlightPrioritization` controls property highlights for v10 property data. Custom attribute definitions can add custom values to rental output. Translation overrides affect localized labels.
+`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`.
+
+For either option, `undefined` uses the SDK default and `[]` emits no highlights.
+Duplicate keys are emitted once; unknown, unsupported, or unresolved keys are
+ignored. When several configured rental view facts have values, only the first one
+in the ordered allowlist is emitted. View-type descriptors qualify a view and are
+not part of this strongest-view selection. Translation overrides affect localized
+labels.
+
+The active defaults are exported as
+`DEFAULT_RENTAL_HIGHLIGHT_PRIORITIZATION` and
+`DEFAULT_RENTAL_PROPERTY_HIGHLIGHT_PRIORITIZATION` from
+`@v-office/sdk-core`. See `versions/2.9.0/CHANGELOG.md` for the release notes and
+`versions/2.9.0/MIGRATION.md` for the complete default lists and upgrade checks.
+
+In CLI JSON, `customAttributes` contains catalog and selection inputs; the CLI builds
+the validated registry. Typed applications normally call `defineCustomAttributes`
+and pass its result instead.
+
+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
+authored `category` — alongside built-in attributes of that category, not in a separate
+bucket. Category and attribute `label`s in the output are localized strings, never
+stable keys. See `custom-attributes.md`.
 
 ## CLI Usage
 

package/instructions/search.md

@@ -272,7 +272,12 @@ Sample:
   "appliedFilters": [
     {
       "key": "wifi",
-      "label": "WiFi"
+      "label": "WLAN"
+    },
+    {
+      "key": "region",
+      "label": "Region: Norden",
+      "value": "north"
     }
   ],
   "unusedFilterKeys": [],
@@ -285,13 +290,34 @@ 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`.
 
+`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
+repeat, so it cannot identify a filter; `key` plus `value` can. `value` is the
+canonical applied value and is present only for filters that carry one — on/off
+filters are identified by `key` alone. A key you sent that is **not** listed here
+appears in `unusedFilterKeys` and had no effect on the result set. A scalar key may
+appear in both arrays when its first value was applied but additional values were
+rejected.
+
+Composition filters are atomic in both metadata and the backend payload. The SDK
+validates all configured leaves against the active backend before committing any
+generated GraphQL or REST input. If one leaf is unsupported or malformed, no
+composition-generated leaf restricts the result, and only the composition key is
+reported unused. Direct filters are tracked independently and remain applied even
+when a failed composition references the same key.
+
+When every leaf succeeds, `appliedFilters` contains both the composition entry and
+the expanded leaf entries. A UI may collapse those leaves under the composition for
+display, but should keep the returned keys and canonical values when removing direct
+filters.
+
 ## v10 Backend
 
 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 a `customAttributeDefinitionManifest`; without it, custom-attribute query keys are left in `unusedFilterKeys` and no custom-attribute highlights are added.
+- 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.
 
@@ -299,7 +325,7 @@ v10 search runs against the dedicated REST search backend (`POST` to the configu
 
 Use flat `WebsiteSDKConfig` files and optional `WebsiteSDKOptions`.
 
-For v10, config requires `searchEndpoint` (the full REST search URL) as of 2.5.0. See `creation.md` for `searchEndpoint` and the `customAttributeDefinitionManifest` option.
+For v10, config requires `searchEndpoint` (the full REST search URL) as of 2.5.0. See `creation.md` for `searchEndpoint` and the `customAttributes` option.
 
 Custom filter definitions can extend accepted search query keys. Search requests are rate-limited to one backend request per second with a queue size of five.
 

package/instructions/versions/2.5.0/MIGRATION.md

@@ -1,5 +1,10 @@
 # Migration: 2.4.3 to 2.5.0
 
+> Custom-attribute manifest guidance below is historically correct for 2.5.x but is
+> superseded in 2.8.0. When upgrading current packages, follow
+> `../2.8.0/MIGRATION.md` to replace `customAttributeDefinitionManifest` with
+> `defineCustomAttributes`.
+
 This guide covers upgrading `@v-office/website-sdk` from 2.4.3 to 2.5.0.
 
 2.5.0 keeps `createWebsiteSDK({ config, options })`, the flat `WebsiteSDKConfig`, and existing SDK calls. v10 search now runs against the dedicated REST search backend, which requires one new config field and, for custom-attribute search, one new option. Search input also gains optional sorting, and static v10 rental loading uses the full Rental APIs internally. Existing calls and output types remain compatible.

package/instructions/versions/2.6.0/CHANGELOG.md

@@ -1,28 +1,6 @@
 # Changelog: 2.6.0
 
-Release date: 2026-07-27
+`@v-office/website-sdk` 2.6.0 was never published. The Stripe Checkout work
+documented under this version during development shipped as 2.7.0 on 2026-07-27.
 
-This release makes v9 `stripe_checkout` payment options submittable. The vOffice `initStripePayment` action returns only session metadata, so `submitPaymentOption` now opens the Checkout Session with Stripe.js when the backend omits the session URL. Config, service calls, and output types are unchanged.
-
-## Added
-
-- `submitPaymentOption` and `submitPaymentOptionEffect` now complete `stripe_checkout` options that carry only `sessionId` and `accountId`. Previously these options failed with "Stripe Checkout requires a checkout session URL".
-- Stripe.js is loaded from `https://js.stripe.com/v3/` on first use and reused for later submissions. A failed load is not kept, so the next submission retries it. An existing `window.Stripe` instance is used when the page already provides one, so no second script tag is added.
-- The vOffice Stripe platform publishable keys are embedded in the SDK. Stripe Checkout requires no consumer configuration.
-
-## Changed
-
-- `stripe_checkout` submission prefers the Checkout Session `url` and only falls back to Stripe.js when it is absent. Once vOffice returns the URL, the SDK uses it without a further release.
-- The publishable key is selected from the session id, so tenants in Stripe test mode (`cs_test_`) and live mode (`cs_live_`) both work without configuration or environment detection.
-- Stripe sessions are created on connected accounts, so the option's `accountId` is passed to Stripe.js as `stripeAccount`.
-- The failure raised when a `stripe_checkout` option carries neither a URL nor a session id now names both.
-- Browser access helpers used by payment submission moved into an internal module shared by redirect, form-post, and Stripe submission. This is internal only and does not change the public API.
-
-## Migration Impact
-
-- Consumers that hid Stripe payment options because `url` was missing can render them again. Gate the button on the option being present rather than on `option.url`. See `versions/2.6.0/MIGRATION.md`.
-- Sites with a Content-Security-Policy must allow `script-src https://js.stripe.com` and `frame-src https://js.stripe.com https://hooks.stripe.com`.
-- Payment submission remains browser-only and still fails outside a browser environment.
-- Stripe.js is fetched at submission time, so payment submission can now fail from a blocked or unavailable third-party script. Treat that as a payment failure, never as a booking failure: the reservation already exists when payment options are shown.
-- No config, option, or output type changes. v10 Adyen `redirect` flows and all `bank_transfer` and `form_post` flows are unaffected.
-- Stripe removed `redirectToCheckout` from its versioned Stripe.js release trains (`clover`, 2025-09-30, and later) and from the published `stripe-js` types. The method is still implemented in the unversioned `https://js.stripe.com/v3/` bundle that the SDK loads, which is why this fallback works. It is a bridge until vOffice returns the session URL and is expected to be removed afterwards. Should a future Stripe.js build drop the method entirely, submission fails with a message naming the missing session URL.
+Use `../2.7.0/CHANGELOG.md` as the authoritative release record.

package/instructions/versions/2.6.0/MIGRATION.md

@@ -1,74 +1,6 @@
-# Migration: 2.5.x to 2.6.0
+# Migration: 2.6.0
 
-This guide covers upgrading `@v-office/website-sdk` from 2.5.0 or 2.5.1 to 2.6.0.
+`@v-office/website-sdk` 2.6.0 was never published. The planned Stripe Checkout
+change shipped in 2.7.0.
 
-2.6.0 changes no config, no service call, and no output type. The only change is that `stripe_checkout` payment options can now be submitted on the v9 backend. If your site does not offer Stripe, upgrading requires no work at all.
-
-## What Changed
-
-vOffice's `initStripePayment` action returns only `sessionId` and `accountId`, never the Checkout Session URL. Because `submitPaymentOption` redirected exclusively to a session URL, Stripe payment options could never be completed and failed with "Stripe Checkout requires a checkout session URL".
-
-2.6.0 keeps the URL redirect as the preferred path and adds a fallback: when a `stripe_checkout` option has a `sessionId` but no `url`, the SDK loads Stripe.js and opens the Checkout Session with it. This is the same mechanism the classic non-SDK vOffice websites use.
-
-The fallback is self-retiring. When vOffice starts returning the session URL, the option gains a `url`, the URL redirect wins, and Stripe.js is never loaded. No SDK release is needed for that transition.
-
-## Remove Stripe Workarounds
-
-Sites that hid the Stripe button because no URL was present should now render it. Gate on the option existing rather than on `option.url`:
-
-```ts
-// Before: Stripe options were unusable, so they had to be hidden
-const payable = option.kind !== "stripe_checkout" || option.url !== undefined;
-
-// After: every submittable option can be submitted
-const payable = true;
-```
-
-Sites that implemented their own Stripe.js bridge with a publishable key can delete it, along with the key configuration. The SDK carries the vOffice platform keys and selects between test and live based on the session id, so a tenant in Stripe test mode and a tenant in live mode both work from the same build.
-
-## Content-Security-Policy
-
-Stripe.js is fetched from Stripe at submission time. If your site sets a CSP, allow:
-
-```
-script-src  https://js.stripe.com
-frame-src   https://js.stripe.com https://hooks.stripe.com
-```
-
-Without these directives the script is blocked and Stripe submission fails. Other payment kinds are unaffected.
-
-## Error Handling
-
-Payment submission can now fail for new reasons: Stripe.js could not be loaded, the loaded Stripe.js build does not provide the Checkout redirect, or Stripe rejected the redirect. All surface as a `CoreSDKError` with `operation: "paymentSubmission"`, the same as existing submission failures.
-
-Offering a retry is worthwhile for these failures. A failed Stripe.js load is not remembered, so the next submission fetches the script again and can succeed without a page reload.
-
-The booking already exists by the time payment options are rendered, so a submission failure must never be presented as a failed booking:
-
-```ts
-try {
-  await sdk.live.booking.submitPaymentOption(option);
-} catch (error) {
-  // The reservation is created. Show the booking number and offer bank transfer.
-  showPaymentFailure({ bookingNumber: booking.bookingNumber, error });
-}
-```
-
-Submission is still browser-only and fails outside a browser environment, unchanged from earlier versions.
-
-## Payment Return
-
-Unchanged from earlier versions, but worth confirming while testing Stripe end to end. The SDK derives the Stripe success and cancel URLs from the `relativeRedirectUrl` passed to `sdk.live.booking.book(...)` and appends `payment=stripe&success=true` or `payment=stripe&cancel=true`. That path must exist in your site and should read those query parameters.
-
-Note that `relativeRedirectUrl` is supplied before the reservation exists, so the return URL cannot contain the booking number or guest token. Persist anything the return page needs, for example in `sessionStorage`, before submitting the payment option.
-
-A `success=true` return means Stripe sent the browser back, not that payment has settled. Payment confirmation reaches vOffice through Stripe's webhook.
-
-## Recommended Steps
-
-1. Upgrade to `@v-office/website-sdk` 2.6.0.
-2. Remove any conditional that hides Stripe payment options when `option.url` is missing.
-3. Remove a site-level Stripe.js bridge and its publishable key configuration if you added one.
-4. Add the Stripe CSP directives if your site sets a Content-Security-Policy.
-5. Confirm payment submission errors are presented as payment failures with the booking number, not as booking failures.
-6. Smoke-test one booking against a Stripe test tenant and one against a live tenant, checking that Checkout opens and that the configured return path handles both `success=true` and `cancel=true`.
+Consumers upgrading from 2.5.x should follow `../2.7.0/MIGRATION.md`.

package/instructions/versions/2.7.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog: 2.7.0
+
+Release date: 2026-07-27
+
+This release makes v9 `stripe_checkout` payment options submittable. The vOffice
+`initStripePayment` action returns only session metadata, so `submitPaymentOption`
+now opens the Checkout Session with Stripe.js when the backend omits the session
+URL. Config, service calls, and output types are unchanged.
+
+## Added
+
+- `submitPaymentOption` and `submitPaymentOptionEffect` now complete
+  `stripe_checkout` options that carry only `sessionId` and `accountId`.
+- Stripe.js is loaded from `https://js.stripe.com/v3/` on first use and reused for
+  later submissions. Failed loads are not cached, and an existing `window.Stripe`
+  is reused.
+- The SDK includes the vOffice Stripe platform publishable keys, so Stripe Checkout
+  needs no consumer key configuration.
+
+## Changed
+
+- `stripe_checkout` prefers a Checkout Session `url` and falls back to Stripe.js
+  only when the URL is absent.
+- Test (`cs_test_`) and live (`cs_live_`) sessions select the corresponding
+  publishable key automatically.
+- Connected-account sessions pass `accountId` to Stripe.js as `stripeAccount`.
+- Missing-session failures now name both the absent URL and session ID.
+
+## Migration Impact
+
+- Sites that hid Stripe options because `url` was absent can render them again.
+  Gate the button on the payment option being present rather than on `option.url`.
+- Content-Security-Policy must allow `script-src https://js.stripe.com` and
+  `frame-src https://js.stripe.com https://hooks.stripe.com`.
+- Payment submission remains browser-only. A Stripe script or redirect failure is
+  a payment failure after the booking exists, not a booking failure.
+- No config, service-call, or output migration is required. See
+  `versions/2.7.0/MIGRATION.md`.
+
+## Versioning Note
+
+The implementation was documented during development under a planned 2.6.0
+directory, but 2.6.0 was never published. The package was released as 2.7.0; this
+directory is the authoritative release record.

package/instructions/versions/2.7.0/MIGRATION.md

@@ -0,0 +1,79 @@
+# Migration: 2.5.x to 2.7.0
+
+This guide covers upgrading `@v-office/website-sdk` from 2.5.0 or 2.5.1 to 2.7.0.
+Version 2.6.0 was not published.
+
+2.7.0 changes no config, service call, or output type. The runtime change is that
+v9 `stripe_checkout` payment options can now be submitted. Sites without Stripe
+need no migration work.
+
+## Remove Stripe Workarounds
+
+vOffice's `initStripePayment` action can return `sessionId` and `accountId` without
+the Checkout Session URL. The SDK now keeps URL redirects as the preferred path and
+uses Stripe.js when only session metadata is available.
+
+Sites that hid Stripe options without a URL should render them:
+
+```ts
+// Before
+const payable = option.kind !== "stripe_checkout" || option.url !== undefined;
+
+// 2.7.0
+const payable = true;
+```
+
+Delete site-level Stripe.js bridges and publishable-key configuration added only to
+work around the missing URL. The SDK selects the vOffice platform test or live key
+from the session ID and passes connected-account context automatically.
+
+## Content-Security-Policy
+
+If the site sets a CSP, allow:
+
+```text
+script-src https://js.stripe.com
+frame-src https://js.stripe.com https://hooks.stripe.com
+```
+
+Without these directives, Stripe submission fails. Other payment kinds are
+unaffected.
+
+## Error Handling
+
+Stripe.js loading or redirecting can fail. These failures surface as
+`CoreSDKError` with `operation: "paymentSubmission"`. A failed script load is not
+cached, so retrying can succeed.
+
+The booking already exists when payment options are rendered. Present a submission
+failure as a payment problem with the booking number, never as a failed booking:
+
+```ts
+try {
+  await sdk.live.booking.submitPaymentOption(option);
+} catch (error) {
+  showPaymentFailure({ bookingNumber: booking.bookingNumber, error });
+}
+```
+
+Submission remains browser-only.
+
+## Payment Return
+
+The SDK derives Stripe success and cancel URLs from the `relativeRedirectUrl`
+passed to `sdk.live.booking.book(...)`, appending
+`payment=stripe&success=true` or `payment=stripe&cancel=true`. Persist anything the
+return page needs before submitting the payment option because the redirect URL is
+configured before the booking number exists.
+
+A `success=true` return means the browser returned from Stripe, not that payment
+settled. Stripe's webhook confirms payment to vOffice.
+
+## Recommended Steps
+
+1. Upgrade to `@v-office/website-sdk` 2.7.0.
+2. Remove checks that hide Stripe options when `option.url` is missing.
+3. Remove any site-owned Stripe.js bridge and publishable key used for this flow.
+4. Add the Stripe CSP directives when applicable.
+5. Present submission failures as post-booking payment failures.
+6. Smoke-test test-mode and live-mode tenants, including success and cancel returns.

package/instructions/versions/2.8.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog: 2.8.0
+
+This release replaces the loose custom-attribute manifest/configuration split with a
+validated catalog-backed registry shared by rental display, highlights, filter
+discovery, and search.
+
+## Added
+
+- `fetchCustomAttributeCatalog({ config })` reads public v10 custom-attribute
+  definition IDs, keys, types, and option identities at build time.
+- `defineCustomAttributes(...)` joins that catalog with authored labels, exposure,
+  display, category, v9 bindings, and option labels.
+- `defineCustomAttributesFromUnknown(...)`, `parseCustomAttributeCatalog`, and
+  `CustomAttributeCatalogSchema` support CLI/JSON and other untyped inputs.
+- The website package exports the catalog, selection, registry, resolved-attribute,
+  category, and override types needed to author typed configuration.
+- v10 reads public custom-attribute values for rentals and search output. v9 can
+  render the same registry through explicit `p_*` rental-data bindings and `v9Only`
+  entries.
+- Applied value-bearing filters include a canonical `value`, allowing consumers to
+  remove one exact filter value without relying on a localized label.
+
+## Changed
+
+- `WebsiteSDKOptions.customAttributes` now receives the validated registry returned
+  by `defineCustomAttributes`.
+- `customAttributeFilterDefinitions` now contains only `backendFilter` and
+  `composition` definitions. Catalog-backed custom attributes get their filter
+  policy from the registry selection.
+- v10 custom-attribute filters are advertised only when filtering is enabled and a
+  backend definition ID exists. v9 does not advertise or execute catalog custom
+  attributes.
+- Public/internal filter exposure and display are independent. Internal filters are
+  queryable and usable by compositions but absent from `getFilters`.
+- Custom-attribute categories, backend-filter categories, and composition
+  categories are returned as localized display labels. Configuration continues to
+  store stable category keys.
+- Composition discovery is backend-aware. Every configured leaf and value must be
+  executable on the active backend.
+- Composition execution is atomic at the GraphQL/REST payload level. A failed
+  composition contributes no generated leaf and reports only its parent key unused.
+- Nested compositions are rejected while recursive expansion remains unsupported.
+- Query-key ownership is validated against period, occupancy, active-backend
+  built-ins, overlapping custom definitions, and repeated configured filter keys.
+- Rental highlight prioritization remains an explicit ordered list. Custom
+  attributes render only when their resolved key is listed; registry contents do
+  not reorder built-in highlights.
+
+## Removed
+
+- `customAttributeDefinitionManifest`,
+  `CustomAttributeDefinitionManifest`,
+  `CustomAttributeDefinitionManifestEntry`, and related manifest helpers.
+- `source: "customAttribute"` entries in `customAttributeFilterDefinitions`.
+- Unsupported composition expression forms `any`, `gte`, and `lte`.
+- `renderCustomAttributeHighlight`; use registry-backed rental/search output, or
+  `renderResolvedCustomAttribute` from `@v-office/sdk-core`.
+
+## Migration Impact
+
+This is a configuration and public-type migration for consumers using custom
+attributes. Consumers that do not configure custom attributes keep the same SDK
+construction and service calls. Follow `versions/2.8.0/MIGRATION.md`.