@v-office/website-sdk 2.7.0 → 2.9.0

package/dist/instructions/versions/2.8.0/MIGRATION.md

@@ -0,0 +1,252 @@
+# Migration: 2.7.0 to 2.8.0
+
+2.8.0 replaces `customAttributeDefinitionManifest` and
+`source: "customAttribute"` filter definitions with one validated custom-attribute
+registry. SDK construction and service method names are unchanged.
+
+Consumers without custom attributes can upgrade without configuration changes.
+
+## 1. Replace the Definition Manifest
+
+Before:
+
+```ts
+const options = defineWebsiteSDKOptions({
+  customAttributeDefinitionManifest: {
+    byKey: {
+      region: {
+        id: "GQYKYgMVh28X7VLGursbkt",
+        key: "region",
+        type: "OPTION",
+        visibility: "PUBLIC",
+      },
+    },
+    byId: {
+      GQYKYgMVh28X7VLGursbkt: {
+        id: "GQYKYgMVh28X7VLGursbkt",
+        key: "region",
+        type: "OPTION",
+        visibility: "PUBLIC",
+      },
+    },
+  },
+});
+```
+
+After:
+
+```ts
+import {
+  defineCustomAttributes,
+  defineWebsiteSDKOptions,
+  fetchCustomAttributeCatalog,
+} from "@v-office/website-sdk";
+
+const catalog = await fetchCustomAttributeCatalog({ config: v10Config });
+
+const customAttributes = defineCustomAttributes({
+  catalog,
+  select: {
+    region: {
+      label: { "de-DE": "Region", "en-US": "Region" },
+      category: "OTHER",
+      filter: true,
+      optionLabels: {
+        north: { "de-DE": "Norden", "en-US": "North" },
+        south: { "de-DE": "Süden", "en-US": "South" },
+      },
+    },
+  },
+});
+
+const options = defineWebsiteSDKOptions({ customAttributes });
+```
+
+`fetchCustomAttributeCatalog` is v10-only, requires a token authorized for the
+public-definition operation, and returns no localized labels. Fetch it in an
+authorized build environment or pin an equivalent literal catalog.
+`defineCustomAttributes` validates the complete catalog/selection join and reports
+all configuration errors together.
+
+## 2. Move Custom-Attribute Filter Policy
+
+Remove every `source: "customAttribute"` entry from
+`customAttributeFilterDefinitions`. Put its behavior in the matching `select`
+entry:
+
+```ts
+select: {
+  occupancyScore: {
+    label: { "de-DE": "Belegung", "en-US": "Occupancy" },
+    category: "ESSENTIALS",
+    filter: {
+      exposure: "public",
+      numericBounds: { min: 1, max: 12 },
+    },
+  },
+}
+```
+
+Use `filter: "internal"` or `filter: { exposure: "internal" }` for a queryable filter
+that must not appear in `getFilters`. Omit `filter` for display only.
+
+`customAttributeFilterDefinitions` remains the home of:
+
+- `backendFilter`: v9 backend-native filters;
+- `composition`: virtual Boolean filters composed from executable leaves.
+
+## 3. Configure Display and v9 Bindings
+
+Display is independent of filter exposure and defaults to `true`. A selected
+catalog attribute can add a v9 rental-data binding:
+
+```ts
+select: {
+  privateSauna: {
+    label: { "de-DE": "Sauna", "en-US": "Sauna" },
+    display: true,
+    filter: true,
+    v9: "p_14418",
+  },
+}
+```
+
+Use `v9Only` for attributes that have no v10 catalog definition:
+
+```ts
+v9Only: {
+  thatchedRoof: {
+    v9: "p_14420",
+    type: "boolean",
+    label: { "de-DE": "Reetdach", "en-US": "Thatched roof" },
+  },
+}
+```
+
+v9 renders bound values but does not advertise or execute catalog custom-attribute
+filters. v10 filtering requires an enabled filter and a catalog ID.
+
+## 4. Update Composition Expressions
+
+Expressions now support equality leaves joined by `all`:
+
+```ts
+expression: {
+  all: [
+    { filter: "privateSauna", value: true },
+    { filter: "maxPersons", value: 4 },
+  ],
+}
+```
+
+Remove `operator`, `gte`, `lte`, and `any`; they never had correct runtime
+semantics. Nested composition references are rejected.
+
+A composition is advertised only if every leaf can execute on the active backend.
+Execution is atomic: if one configured leaf is unknown, unsupported, malformed, or
+conflicts with a direct value, no generated composition leaf enters the backend
+payload and only the composition key is unused.
+
+Successful compositions return the parent and expanded leaves in `appliedFilters`.
+
+## 5. Rename Colliding Query Keys
+
+Every query key must have one owner. Configuration rejects:
+
+- period/occupancy keys such as `start`, `adults`, and `pets`;
+- filterable custom attributes or compositions that reuse v10 built-in filter keys;
+- configured v9 filters that reuse v9 stable filter keys;
+- a custom attribute and custom filter definition with the same key.
+- repeated keys within `customAttributeFilterDefinitions`.
+
+Use the selection's `key` override when a workspace definition collides:
+
+```ts
+select: {
+  sauna: {
+    key: "privateSauna",
+    label: { "de-DE": "Sauna", "en-US": "Sauna" },
+    filter: true,
+  },
+}
+```
+
+Update query URLs and `rentalHighlightPrioritization` to the resolved key.
+
+## 6. Treat Categories as Display Labels
+
+Configuration keeps stable keys such as `OUTDOORS`. `getFilters` and rental
+attribute groups return localized labels such as `Außenbereich` or `Outdoor Area`.
+Do not compare output categories to stable keys. Customize wording with
+locale-nested overrides:
+
+```ts
+translationOverrides: {
+  "de-DE": {
+    "RentalAttributesCategory.OUTDOORS.label": "Draußen",
+  },
+}
+```
+
+## 7. Update Highlight Configuration
+
+Custom attributes appear in rental/search `highlights` only when their resolved key
+is listed in `rentalHighlightPrioritization`:
+
+```ts
+rentalHighlightPrioritization: ["bedrooms", customAttributes.keys.region, "bathrooms"];
+```
+
+The list remains authoritative for order. Registry contents do not reorder
+built-ins, duplicate keys render once, and a built-in metadata key shadows a
+same-named display-only custom attribute.
+
+## 8. Update Applied-Filter Handling
+
+Value-bearing applied filters now include canonical `value`:
+
+```ts
+{ key: "region", label: "Region: North", value: "north" }
+```
+
+Use `key` plus `value` to remove an exact filter. Labels remain localized
+presentation and are not identifiers. A scalar key may appear in both
+`appliedFilters` and `unusedFilterKeys` when one value applied and another was
+rejected.
+
+## 9. CLI and Untyped Options
+
+CLI JSON supplies catalog and selection **inputs**, not a finished registry:
+
+```json
+{
+  "customAttributes": {
+    "catalog": {
+      "privateSauna": {
+        "id": "GQYKYgMVh28X7VLGursbkt",
+        "type": "BOOLEAN"
+      }
+    },
+    "select": {
+      "privateSauna": {
+        "label": { "de-DE": "Sauna", "en-US": "Sauna" },
+        "filter": true
+      }
+    }
+  }
+}
+```
+
+The CLI uses `defineCustomAttributesFromUnknown` and applies the same runtime
+validation as typed configuration.
+
+## Recommended Verification
+
+1. Run `getFilters` for v9 and v10 in both locales.
+2. Confirm internal filters are absent while public compositions using them remain
+   executable.
+3. Inspect v9 GraphQL and v10 REST variables for one successful and one failed
+   composition.
+4. Verify renamed custom attributes render in rentals, search highlights, URLs, and
+   applied-filter chips.
+5. Verify `rentalHighlightPrioritization` order with and without custom attributes.

package/dist/instructions/versions/2.9.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog: 2.9.0
+
+This release makes highlight selection explicit, improves the default rental and
+property rankings across coastal, lake, and mountain portfolios, and removes
+duplicate rental views.
+
+## Changed
+
+- `rentalHighlightPrioritization` and
+  `rentalPropertyHighlightPrioritization` are documented as ordered allowlists,
+  not sorts over every available fact. A key that is not listed is not emitted as
+  a highlight even when the source contains a value.
+- The default rental allowlist now starts with capacity and size, moves distinctive
+  views and facilities ahead of common fittings, places `youthgroups` last, and
+  includes previously omitted terrain-specific and practical facts.
+- `outdoorPool`, `indoorPool`, lake, mountain, countryside, river, and secondary
+  views can now appear through the default rental highlights, alongside facilities
+  such as `spa`, `terrace`, `lift`, `garage`, `dryer`, and `skiBootWarmer`.
+- The default v10 property allowlist now prioritizes beach location and shared
+  facilities ahead of utilities. It also includes `locLake`, `lakedistance`,
+  `locMountain`, and `skidistance`.
+- Rental highlights now emit only the first configured view fact that has a value.
+  The configured order defines which view is strongest. View-type descriptors such
+  as `seaviewType` remain independent qualifiers.
+- Strongest-view selection applies consistently to v10 and legacy v9 rental
+  highlights. Keys unsupported by the active backend remain ignored.
+
+## Migration Impact
+
+- Sites using the SDK defaults may receive a different highlight order and more
+  highlight values.
+- Sites that displayed several simultaneous rental views now receive at most one
+  view highlight.
+- Explicit custom allowlists retain their configured order and membership, apart
+  from the new strongest-view rule.
+- No SDK construction, service-call, or output-type changes are required. Review
+  `versions/2.9.0/MIGRATION.md` before upgrading.

package/dist/instructions/versions/2.9.0/MIGRATION.md

@@ -0,0 +1,153 @@
+# Migration: 2.8.0 to 2.9.0
+
+2.9.0 changes default highlight membership and order and emits at most one rental
+view highlight. Configuration and output types are unchanged.
+
+## 1. Treat Highlight Configuration as an Ordered Allowlist
+
+`rentalHighlightPrioritization` and
+`rentalPropertyHighlightPrioritization` select which facts become highlights and
+set their order. They do not sort a complete list generated elsewhere.
+
+- An omitted key is not emitted even when the source contains a value.
+- `undefined` uses the SDK default.
+- `[]` emits no highlights.
+- Duplicate keys are evaluated once.
+- Unknown, unresolved, or backend-unsupported keys are ignored.
+- These options affect `highlights`, not `attributes` or `vicinity`.
+
+Audit custom lists that were shortened only to express a preferred order. Add every
+fact that must remain eligible for highlight output.
+
+## 2. Review the New Rental Default
+
+The default rental allowlist is now:
+
+```ts
+[
+  "maxPersons",
+  "bedrooms",
+  "squareMeters",
+  "bathrooms",
+  "seaview",
+  "lakeview",
+  "mountainview",
+  "valleyView",
+  "countrysideView",
+  "riverView",
+  "outdoorPool",
+  "indoorPool",
+  "sauna",
+  "spa",
+  "whirlpool",
+  "balcony",
+  "terrace",
+  "garden",
+  "beachChair",
+  "landingStage",
+  "boatBerth",
+  "skiBootWarmer",
+  "detached",
+  "fireplace",
+  "bbq",
+  "gym",
+  "closedPlot",
+  "beachview",
+  "gardenView",
+  "poolView",
+  "cityView",
+  "quietStreetView",
+  "innerCourtView",
+  "washer",
+  "dryer",
+  "privateparking",
+  "garage",
+  "carport",
+  "wifi",
+  "lift",
+  "childrenWelcome",
+  "nonsmoking",
+  "kitchen",
+  "dishwasher",
+  "tv",
+  "ac",
+  "heating",
+  "fridge",
+  "microwave",
+  "oven",
+  "stove",
+  "coffeemaker",
+  "freezer",
+  "electricKettle",
+  "youthgroups",
+];
+```
+
+Capacity and size come first, followed by distinctive views, facilities, outdoor
+space, terrain-specific draws, practical confirmers, common fittings, and finally
+the minority booking rule `youthgroups`.
+
+## 3. Review the New Property Default
+
+Property highlights apply only to v10 property data. Their default allowlist is:
+
+```ts
+[
+  "beachfront",
+  "beachaccess",
+  "beachdistance",
+  "seadistance",
+  "locBeach",
+  "locLake",
+  "lakedistance",
+  "locMountain",
+  "skidistance",
+  "outdoorPool",
+  "indoorPool",
+  "garden",
+  "terrace",
+  "bbqFacilities",
+  "playground",
+  "pool4kids",
+  "familyRoomsAvailable",
+  "parking",
+  "wifi",
+  "washer",
+  "dryer",
+  "ac",
+  "heating",
+  "locGroceries",
+  "restaurantdistance",
+  "publictransportdistance",
+];
+```
+
+Location and terrain now precede shared facilities, family signals, utilities, and
+secondary map facts.
+
+## 4. Expect One Rental View Highlight
+
+When several configured view facts have values, only the first one in
+`rentalHighlightPrioritization` is emitted:
+
+```ts
+rentalHighlightPrioritization: ["mountainview", "lakeview", "seaview", "gardenView", "wifi"];
+```
+
+For this configuration, a rental with both mountain and lake views emits only the
+mountain view. If `mountainview` has no value, the lake view can emit instead.
+View-type descriptors such as `mountainviewType` and `seaviewType` qualify a view
+and do not compete for the single view slot.
+
+The rule applies to v10 and legacy v9. An unsupported v9 view key does not prevent
+a later supported view from being emitted.
+
+## Recommended Verification
+
+1. Check search cards and rental pages that truncate highlights.
+2. Compare coastal, lake, and mountain workspaces against the new defaults.
+3. Confirm capacity and size remain available to consumers that read them from
+   search highlights.
+4. Verify rentals with cumulative view facts emit the expected first configured
+   view.
+5. Review explicit custom allowlists for facts that were unintentionally omitted.

package/dist/{rentals-Lw1qUKIj.mjs → rentals-CFod9H4m.mjs}

@@ -1,5 +1,5 @@
-import { c as VofficeUnitDataFieldSchemas, d as VofficeUnitDataPropertyMetadata, f as parseVofficeFacilityData, i as toLocalizedString, l as VofficeUnitDataPropertyCategoryLabelKeys, m as parseVofficeUnitData, n as toImages, o as rentalsAllFeedbacksQuery, p as parseVofficeFeedbackData, r as toAddress, s as rentalsAllWithoutFeedbacksQuery, t as toRentalHighlights, u as VofficeUnitDataPropertyCategoryValues } from "./to-rental-highlights-CxWlq76f.mjs";
-import { makeTranslate, renderCustomAttributeHighlight, renderLabeledAttributeValue } from "@v-office/sdk-core";
+import { c as VofficeUnitDataFieldSchemas, d as VofficeUnitDataPropertyMetadata, f as parseVofficeFacilityData, i as toLocalizedString, l as VofficeUnitDataPropertyCategoryLabelKeys, m as parseVofficeUnitData, n as toImages, o as rentalsAllFeedbacksQuery, p as parseVofficeFeedbackData, r as toAddress, s as rentalsAllWithoutFeedbacksQuery, t as toRentalHighlights, u as VofficeUnitDataPropertyCategoryValues } from "./to-rental-highlights-B6a_fi0j.mjs";
+import { makeTranslate, renderLabeledAttributeValue, renderResolvedCustomAttribute, toCustomAttributeList, toResolvedCustomAttributeCategoryTranslationKey } from "@v-office/sdk-core";
 import { Effect } from "effect";
 //#region src/legacy-v9/parser/rentals/to-description.ts
 const toDescription = (data, locale) => {
@@ -60,29 +60,30 @@ const PROPERTY_METADATA_ENTRIES = Object.entries(VofficeUnitDataPropertyMetadata
 	return (CATEGORY_ORDER.get(left.metadata.category.key) ?? Number.MAX_SAFE_INTEGER) - (CATEGORY_ORDER.get(right.metadata.category.key) ?? Number.MAX_SAFE_INTEGER) || left.index - right.index;
 });
 const canRenderLabeledAttributeValue$1 = (value) => value !== false && value !== 0 && value !== "false" && value !== "0" && value != null && value !== "";
-const toRentalAttributes = ({ locale, translations, attributes, customAttributeFilterDefinitions }) => Effect.gen(function* () {
+const toRentalAttributes = ({ locale, translations, attributes, customAttributes }) => Effect.gen(function* () {
 	const result = [];
 	const categoriesByKey = /* @__PURE__ */ new Map();
 	const subCategoriesByKey = /* @__PURE__ */ new Map();
 	const knownAttributes = attributes.known;
 	const translate = makeTranslate(translations, locale);
-	const getGeneralSubCategory = () => Effect.gen(function* () {
-		let category = categoriesByKey.get(GENERAL_CATEGORY$1.key);
+	const getCustomAttributeSubCategory = (categoryKey) => Effect.gen(function* () {
+		const labelKey = toResolvedCustomAttributeCategoryTranslationKey(categoryKey);
+		let category = categoriesByKey.get(categoryKey);
 		if (category == null) {
 			category = {
-				label: yield* translate(GENERAL_CATEGORY$1.labelKey, GENERAL_CATEGORY$1.key),
+				label: yield* translate(labelKey, categoryKey),
 				subCategories: []
 			};
-			categoriesByKey.set(GENERAL_CATEGORY$1.key, category);
+			categoriesByKey.set(categoryKey, category);
 			result.push(category);
 		}
-		let subCategory = subCategoriesByKey.get(GENERAL_CATEGORY$1.key);
+		let subCategory = subCategoriesByKey.get(categoryKey);
 		if (subCategory == null) {
 			subCategory = {
 				label: category.label,
 				items: []
 			};
-			subCategoriesByKey.set(GENERAL_CATEGORY$1.key, subCategory);
+			subCategoriesByKey.set(categoryKey, subCategory);
 			category.subCategories.push(subCategory);
 		}
 		return subCategory;
@@ -118,18 +119,17 @@ const toRentalAttributes = ({ locale, translations, attributes, customAttributeF
 		}
 		subCategory.items.push(attribute);
 	}
-	const customAttributeItems = [];
-	for (const definition of customAttributeFilterDefinitions) {
-		const value = knownAttributes[definition.key] ?? attributes.unknown[definition.key];
-		const attribute = renderCustomAttributeHighlight({
-			definitions: customAttributeFilterDefinitions,
-			key: definition.key,
+	for (const attribute of toCustomAttributeList(customAttributes)) {
+		const binding = attribute.v9;
+		if (binding === void 0) continue;
+		const rendered = renderResolvedCustomAttribute({
+			attribute,
 			locale,
-			value
+			value: knownAttributes[binding] ?? attributes.unknown[binding]
 		});
-		if (attribute != null) customAttributeItems.push(attribute);
+		if (rendered == null) continue;
+		(yield* getCustomAttributeSubCategory(attribute.category)).items.push(rendered);
 	}
-	if (customAttributeItems.length > 0) (yield* getGeneralSubCategory()).items.push(...customAttributeItems);
 	return result;
 });
 //#endregion
@@ -228,7 +228,7 @@ const toReviews = ({ locale, translations, rental }) => Effect.gen(function* ()
 });
 //#endregion
 //#region src/legacy-v9/parser/rentals/to-rental-list-item.ts
-const toRentalRentalsOutput = ({ rental, locale, translations, imageProxyBaseUrl, rentalHighlightPrioritization, customAttributeFilterDefinitions }) => Effect.gen(function* () {
+const toRentalRentalsOutput = ({ rental, locale, translations, imageProxyBaseUrl, rentalHighlightPrioritization, customAttributes }) => Effect.gen(function* () {
 	const data = parseVofficeUnitData(rental.data);
 	const rawRentalType = data.known.type?.trim();
 	const translatedRentalType = rawRentalType != null && rawRentalType.length > 0 ? yield* toRentalType({
@@ -244,7 +244,7 @@ const toRentalRentalsOutput = ({ rental, locale, translations, imageProxyBaseUrl
 		locale,
 		translations,
 		attributes: data,
-		customAttributeFilterDefinitions
+		customAttributes
 	});
 	const vicinity = yield* toRentalVicinity({
 		locale,
@@ -255,7 +255,7 @@ const toRentalRentalsOutput = ({ rental, locale, translations, imageProxyBaseUrl
 		locale,
 		translations,
 		highlightPrioritization: rentalHighlightPrioritization,
-		customAttributeFilterDefinitions,
+		customAttributes,
 		attributes: data
 	});
 	const reviews = yield* toReviews({