@v-office/website-sdk 2.17.0 → 2.18.0

package/instructions/versions/2.18.0/MIGRATION.md

@@ -0,0 +1,364 @@
+# Migration: 2.17.1 to 2.18.0
+
+2.18.0 adds an opt-in legacy-v9 facility association for tenants whose
+facilities reference vOffice object groups through a custom `p_*` data
+attribute. It also exposes initial-availability calendar prices on available
+dates that cannot be used as a start date, and combines repeated included
+rent rows when a quoted stay crosses seasonal rates.
+
+The default facility association and the public static rental result remain
+unchanged when the new config field is omitted. Public availability and quote
+types are unchanged.
+
+## 1. Upgrade
+
+```sh
+pnpm add @v-office/website-sdk@2.18.0
+```
+
+## 2. Keep the Default Relation When Available
+
+No configuration change is required when vOffice units already carry their
+native facility relation:
+
+```ts
+const sdk = createWebsiteSDK({
+  config: {
+    backend: "v9",
+    graphqlUrl: "https://example.com/graphql",
+    apiKey: "...",
+    imageProxyBaseUrl: "https://images.example.com",
+  },
+});
+```
+
+This continues to load the nested `voffice_facility` for each unit. It does not
+request top-level facilities or object-group memberships.
+
+## 3. Enable Object-Group Association When Required
+
+Set the numeric suffix of the facility custom attribute that contains the
+related object-group ID or IDs:
+
+```ts
+const sdk = createWebsiteSDK({
+  config: {
+    backend: "v9",
+    graphqlUrl: "https://example.com/graphql",
+    apiKey: "...",
+    imageProxyBaseUrl: "https://images.example.com",
+    facilityObjectGroupRelationAttributeId: 18962,
+  },
+});
+```
+
+The SDK converts `18962` to the GraphQL facility data attribute `p_18962`.
+Do not pass `"p_18962"` or another string; the config value is a positive
+integer.
+
+When enabled, `getRentals`:
+
+1. Loads all units with `voffice_groups { voffice_group_id }`.
+2. Loads all facilities and requests `p_18962` alongside the normal facility
+   attributes.
+3. Associates each unit with the facility whose configured object-group IDs
+   contain one of the unit's group memberships.
+4. Exposes the resolved facility through the existing `rental.property`.
+5. Applies static rental scope and then loads feedbacks for retained rentals.
+
+### Expanded v9 property fields
+
+Both native and object-group v9 facility relations now populate more of the
+existing `rental.property` shape when the Hub provides the source data:
+
+- `propertyType` from `type`
+- `location` from the GeoJSON `loc`
+- `address` from `address`, with `regionName` used as `province`
+- all existing description components from their corresponding localized
+  facility fields
+- `attributes` for `allergic`, `childrenWelcome`, `pets`, and `youthgroups`
+
+`HOUSE_FAC` becomes `HOLIDAY_HOME_COMPLEX` and `FLAT_FAC` becomes
+`APARTMENT_COMPLEX`. `HOTEL`, `HOSTEL`, `FARM`, and `CAMPGROUND` already match
+the shared values. The normalized value is localized through
+`Property.propertyType.option.*` before it is returned. Unknown facility types
+are omitted.
+
+This uses the existing core `RentalPropertySchema`; no public property field or
+type was added. Missing, empty, zero-valued, or malformed optional source data
+remains omitted. The release does not synthesize property `vicinity` from
+unrelated facility fields.
+
+To select and order v9 property highlights, use the existing website option:
+
+```ts
+const sdk = createWebsiteSDK({
+  config,
+  options: {
+    rentalPropertyHighlightPrioritization: ["childrenWelcome", "pets", "youthgroups"],
+  },
+});
+```
+
+The v9 renderer supports the typed facility attributes `allergic`,
+`childrenWelcome`, `pets`, and `youthgroups`. It preserves the configured order,
+deduplicates keys, and ignores unsupported, missing, or non-renderable values.
+Rental custom attributes are not considered for property highlights.
+
+## 4. Add Tenant-Specific Facility Highlight Text
+
+Use a v9 property-highlight source when a facility custom field contains
+editor-authored highlight lines, such as `p_18963` ("Anlagen Highlights"):
+
+```ts
+import {
+  createWebsiteSDK,
+  defineV9PropertyHighlightSources,
+  defineWebsiteSDKOptions,
+} from "@v-office/website-sdk";
+
+const v9PropertyHighlightSources = defineV9PropertyHighlightSources({
+  facilityHighlights: {
+    v9: "p_18963",
+    type: "line-list",
+  },
+});
+
+const sdk = createWebsiteSDK({
+  config,
+  options: defineWebsiteSDKOptions({
+    v9PropertyHighlightSources,
+    rentalPropertyHighlightPrioritization: [
+      "childrenWelcome",
+      v9PropertyHighlightSources.keys.facilityHighlights,
+      "pets",
+    ],
+  }),
+});
+```
+
+The registry gives the tenant-specific field a stable public selection key.
+Defining a source alone does not request or emit it; add the generated key to
+`rentalPropertyHighlightPrioritization`. The selected `p_*` field is requested
+for both native and object-group facility relations.
+
+Source keys must not reuse the built-in v9 facility keys `allergic`,
+`childrenWelcome`, `pets`, or `youthgroups`; registry creation rejects those
+collisions.
+
+`line-list` resolves the localized field value, splits it at Unix or Windows
+newlines, trims each line, drops empty lines, and deduplicates exact visible
+values while preserving order. Each remaining line becomes one
+`property.highlights` item at the source key's position. Missing and `null`
+values emit nothing. Semicolons remain text; use one highlight per line in
+vOffice.
+
+For CLI JSON, provide the authored source definitions directly:
+
+```json
+{
+  "v9PropertyHighlightSources": {
+    "facilityHighlights": {
+      "v9": "p_18963",
+      "type": "line-list"
+    }
+  },
+  "rentalPropertyHighlightPrioritization": ["childrenWelcome", "facilityHighlights", "pets"]
+}
+```
+
+The CLI builds and validates the registry. TypeScript consumers should use
+`defineV9PropertyHighlightSources` so `keys.facilityHighlights` is inferred and
+checked.
+
+## 5. Prepare the GraphQL Hub
+
+Before enabling the config, verify that the same API key can query:
+
+```graphql
+query FacilityObjectGroupRelations {
+  facilities: voffice_facilities(language: "de") {
+    id
+    name
+    data(attributes: ["p_18962", "p_18963"])
+  }
+
+  all(language: "de") {
+    voffice_id
+    voffice_groups {
+      voffice_group_id
+    }
+  }
+}
+```
+
+The Hub must return:
+
+- the required facilities from `voffice_facilities`
+- a usable relation value in the configured `p_*` attribute
+- any selected facility highlight `p_*` values
+- matching `voffice_group_id` values on the intended units
+
+Do not enable the mode while those resources are only available through v0 or
+v1 and have not yet synchronized to GraphQL.
+
+## 6. Account for Relation Validation
+
+The relation attribute can contain positive numeric IDs as numbers, numeric
+strings, localized string records, arrays, or strings separated by whitespace,
+commas, or semicolons.
+
+The static request fails rather than selecting an arbitrary property when:
+
+- no facility has a usable configured relation value
+- a non-empty relation value cannot be interpreted as positive integer IDs
+- two facilities claim the same object-group ID
+- one unit matches object groups belonging to different facilities
+
+One facility may reference several groups. One unit may match several groups
+when all of them resolve to the same facility.
+
+Facilities whose relation is empty contribute no association. Rentals with no
+matching relation remain in the result and omit `property`. Compatibility mode
+does not fall back to the native facility relation.
+
+## 7. Account for Batched Catalogue Requests
+
+Legacy-v9 static rentals now load a small ordered rental-ID list first. Complete
+rental details and feedbacks are then requested sequentially in batches of 128
+IDs. Object-group mode loads the facility list once.
+
+The public result and rental order are unchanged. HTTP mocks, request counters,
+and GraphQL tracing that expected one detail query and one feedback query must
+allow multiple requests for catalogues larger than 128 rentals.
+
+Do not combine the detail batches into GraphQL aliases in one HTTP request. The
+separate requests are intentional because they bound the amount of data the
+Laravel/PHP Hub must construct and serialize at once.
+
+## 8. Keep Other APIs Unchanged
+
+The facility-association config only changes legacy-v9 static `getRentals`.
+It does not change:
+
+- v9 live search or its `falicityid` rental-scope filter
+- quote inputs, booking, or contact requests
+- start-date-selected availability
+- shared core rental types
+
+If an application uses both static rental scope and live search, verify both
+flows separately because object-group association is intentionally limited to
+the static catalogue.
+
+## 9. Render Prices on Available Non-Start Dates
+
+`getInitialAvailability` can now return a non-null `formattedPrice` on
+available dates whose status is `check_in_not_allowed` or
+`no_valid_check_out_from_start`:
+
+```ts
+const availability = await sdk.live.availability.getInitialAvailability(input);
+
+for (const [date, day] of Object.entries(availability.calendarDays)) {
+  renderCalendarDay({
+    date,
+    status: day.status,
+    price: day.formattedPrice,
+  });
+}
+```
+
+`formattedPrice` is already localized for the input locale. Render it
+directly when non-null. Do not treat a missing price as the only signal that
+a date is unavailable; use `isAvailableDate` and `status`.
+
+The field remains `null` when:
+
+- the calendar marks the day unavailable
+- the source supplies no numeric price
+
+Start-date-selected availability still has no calendar prices. The v10 change
+is delivered by `@v-office/sdk-core`. Refresh the lockfile when upgrading the
+website SDK so it resolves the coordinated core version shipped for 2.18.0.
+
+## 10. Render Combined Seasonal Rent Lines
+
+Included booking-card subitems that share the same localized `position` and
+`appliedCharge` are now one row on both v9 and v10. A stay that crosses
+seasonal rental prices therefore shows a single rent line such as `Miete` /
+`Inklusive` instead of repeating that row once per rate period.
+
+Cleaning, linen, booking fees, and other distinct included labels remain
+separate. The inclusive total still sums every backend rent period; only the
+repeated display rows are combined. Quote inputs and the booking-card schema
+are unchanged.
+
+Render `subItems` as returned. Do not reconstruct a seasonal breakdown from
+duplicate rent labels; those duplicates are no longer emitted. The v10 change
+is delivered by `@v-office/sdk-core`. Refresh the lockfile when upgrading the
+website SDK so it resolves the coordinated core version shipped for 2.18.0.
+
+## Required Consumer Work
+
+Consumers using the default native facility relation and selected availability
+fields only need to upgrade.
+
+Consumers enabling object-group association should:
+
+1. Confirm GraphQL synchronization for facilities, relation values, and groups.
+2. Add `facilityObjectGroupRelationAttributeId` to the v9 config.
+3. Confirm expected rentals contain `property`.
+4. Keep unmatched rentals without `property` valid.
+5. Update complete-output snapshots that gain associated properties.
+6. Update v9 property snapshots that gain `propertyType`, `location`, `address`,
+   description components, or built-in attributes.
+
+Consumers enabling custom v9 property highlight text should:
+
+1. Confirm the facility `p_*` field has synchronized to GraphQL.
+2. Define it with `defineV9PropertyHighlightSources`.
+3. Select its stable key in `rentalPropertyHighlightPrioritization`.
+4. Keep missing or `null` source values valid.
+5. Update complete rental snapshots that gain property highlight lines.
+
+Consumers that snapshot or hide calendar prices should:
+
+1. Render `formattedPrice` directly when non-null, including on available
+   dates that cannot be used as a start date.
+2. Keep `formattedPrice: null` valid for unavailable and price-less dates.
+3. Refresh the lockfile so v10 resolves the coordinated core release.
+4. Update complete initial-availability snapshots that expected `null` on
+   `check_in_not_allowed` or `no_valid_check_out_from_start`.
+
+Consumers that snapshot or expand included quote rows should:
+
+1. Keep rendering each included `subItem` as one row.
+2. Update complete quote snapshots that expected one rent row per seasonal
+   rate period.
+3. Refresh the lockfile so v10 resolves the coordinated core release.
+
+## Recommended Verification
+
+1. Run `getRentals` without the config and confirm native facility associations
+   remain unchanged.
+2. Run it with the configured attribute ID and count rentals by `property.id`.
+3. Verify a facility that references several groups receives every intended
+   rental once.
+4. Verify unmatched rentals remain present without `property`.
+5. Verify the configured `rentalScope.propertyId`, when used, returns only the
+   resolved facility's rentals.
+6. Verify populated facility location, address, type, descriptions, and
+   attributes are represented in `rental.property`.
+7. Test at least one catalogue larger than 128 rentals so detail and feedback
+   batching are exercised.
+8. Select a configured line-list source between two built-in property keys and
+   confirm its non-empty lines appear at that exact position without duplicates.
+9. Confirm an unselected source is not requested or emitted.
+10. Load initial availability for a stay-through or closed-on-arrival date that
+    has a source price and confirm `formattedPrice` is non-null.
+11. Confirm unavailable and price-less dates retain `formattedPrice: null`.
+12. Confirm start-date-selected availability still has no calendar prices.
+13. Quote a stay that crosses a seasonal rental-price change and confirm the
+    included section shows one rent row.
+14. Confirm other included labels still appear as separate rows and that the
+    inclusive total is unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v-office/website-sdk",
-  "version": "2.17.0",
+  "version": "2.18.0",
   "description": "Website-facing SDK facade backed by @v-office/sdk-core",
   "bin": {
     "website-sdk": "./dist/cli.mjs"
@@ -42,7 +42,7 @@
   },
   "dependencies": {
     "@graphql-typed-document-node/core": "3.2.0",
-    "@v-office/sdk-core": "^1.18.0",
+    "@v-office/sdk-core": "^1.19.0",
     "effect": "4.0.0-beta.85",
     "graphql": "17.0.2",
     "yaml": "^2.9.0"
@@ -77,8 +77,9 @@
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check",
     "check": "pnpm run typecheck && pnpm run lint && pnpm run fmt:check",
-    "test": "pnpm run test:v9:properties && pnpm run test:v9:availability && pnpm run build && node --test test/*.test.mjs",
-    "test:v9:properties": "node --test codegen/v9/heuristic-generation/generate/property.test.ts src/legacy-v9/parser/rentals/render-property-attribute.test.ts src/legacy-v9/parser/rentals/to-rooms.test.ts",
+    "test": "pnpm run test:v9:properties && pnpm run test:v9:rentals && pnpm run test:v9:availability && pnpm run build && node --test test/*.test.mjs",
+    "test:v9:properties": "node --test codegen/v9/heuristic-generation/generate/property.test.ts src/legacy-v9/property-highlight-sources.test.ts src/legacy-v9/parser/rentals/render-property-attribute.test.ts src/legacy-v9/parser/rentals/to-property.test.ts src/legacy-v9/parser/rentals/to-rooms.test.ts",
+    "test:v9:rentals": "node --test src/legacy-v9/static/associate-rentals-with-facilities-by-object-groups.test.ts",
     "test:v9:availability": "node --test src/legacy-v9/parser/availability/to-initial-availability-calendar-days.test.ts",
     "playground:custom-attributes": "pnpm run build && node --env-file=.env playground/custom-attributes.ts"
   }