@v-office/website-sdk 2.13.0 → 2.15.0

package/instructions/CHANGELOG.md

@@ -4,6 +4,8 @@ This file is the versioned changelog index for the website SDK instructions.
 
 ## Versions
 
+- `versions/2.15.0/CHANGELOG.md`: `@v-office/website-sdk` 2.15.0 release notes.
+- `versions/2.14.0/CHANGELOG.md`: `@v-office/website-sdk` 2.14.0 release notes.
 - `versions/2.13.0/CHANGELOG.md`: `@v-office/website-sdk` 2.13.0 release notes.
 - `versions/2.12.0/CHANGELOG.md`: `@v-office/website-sdk` 2.12.0 release notes.
 - `versions/2.11.0/CHANGELOG.md`: `@v-office/website-sdk` 2.11.0 release notes.

package/instructions/MIGRATION.md

@@ -4,6 +4,8 @@ This file is the versioned migration index for the website SDK instructions.
 
 ## Available Guides
 
+- `versions/2.15.0/MIGRATION.md`: migrate from `@v-office/website-sdk` 2.14.0 to 2.15.0.
+- `versions/2.14.0/MIGRATION.md`: migrate from `@v-office/website-sdk` 2.13.0 to 2.14.0.
 - `versions/2.13.0/MIGRATION.md`: migrate from `@v-office/website-sdk` 2.12.0 to 2.13.0.
 - `versions/2.12.0/MIGRATION.md`: migrate from `@v-office/website-sdk` 2.11.0 to 2.12.0.
 - `versions/2.11.0/MIGRATION.md`: migrate from `@v-office/website-sdk` 2.10.0 to 2.11.0.

package/instructions/README.md

@@ -1,7 +1,7 @@
 # Website SDK Instructions
 
 These instructions describe the current source targeted for
-`@v-office/website-sdk` 2.13.0. Package versions remain unchanged until the release
+`@v-office/website-sdk` 2.15.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,12 @@ 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.15.0/`: 2.15.0 v9 facility images in normalized
+  `property.images`, responsive vOffice image URLs, and the 2.14.0-to-2.15.0
+  migration guide.
+- `versions/2.14.0/`: 2.14.0 catalog-backed v9 property types and options,
+  corrected option/count rendering and translations, and the 2.13.0-to-2.14.0
+  migration guide.
 - `versions/2.13.0/`: 2.13.0 static search capability discovery, shared v9/v10
   booking-payment output, corrected remaining-payment deadlines, opaque booking
   credentials, and the 2.12.0-to-2.13.0 migration guide.
@@ -87,5 +93,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.13.0. v10 config additionally requires `searchEndpoint` as
+in 2.0.0 and kept in 2.15.0. v10 config additionally requires `searchEndpoint` as
 of 2.5.0.

package/instructions/rentals.md

@@ -54,7 +54,7 @@ Sample item:
     "headline": "Holiday apartment near the sea",
     "description": "Short localized rental description."
   },
-  "highlights": ["2 bedrooms", "WiFi", "Parking"],
+  "highlights": ["2 bedrooms", "Wi-Fi", "Parking"],
   "attributes": [
     {
       "label": "Amenities",
@@ -87,6 +87,87 @@ Sample item:
 
 Optional fields include `scope`, `address`, `property`, `rooms`, `roomSummary`, `vicinity`, and `reviews`.
 
+### Legacy v9 Facility Images
+
+From 2.15.0, v9 static rentals request facility image metadata and return it in
+`property.images`:
+
+```json
+{
+  "property": {
+    "id": "1512",
+    "nameOrLabel": "Haus Köbesine",
+    "images": [
+      {
+        "idOrPath": "28458352",
+        "src": "https://dyn.v-office.com/image/xl/28458352.jpg",
+        "srcset": "https://dyn.v-office.com/image/tn/28458352.jpg 141w, https://dyn.v-office.com/image/tnx/28458352.jpg 225w, https://dyn.v-office.com/image/s/28458352.jpg 450w, https://dyn.v-office.com/image/m/28458352.jpg 600w, https://dyn.v-office.com/image/xl/28458352.jpg 1440w, https://dyn.v-office.com/image/xxl/28458352.jpg 2400w",
+        "alt": "Hauptansicht",
+        "title": "Hauptansicht",
+        "category": "buildingMain"
+      }
+    ]
+  }
+}
+```
+
+Facility image `src` and `srcset` URLs use `dyn.v-office.com`. Top-level v9
+rental `images` continue to use the configured `imageProxyBaseUrl`. Consumers
+must allow both origins when they render both collections.
+
+The SDK supplies width-descriptor `srcset`; the UI remains responsible for an
+HTML `sizes` attribute that matches its layout. `property.images` is omitted
+when the facility has no usable image IDs. Because the service returns one item
+per rental, rentals in the same facility contain the same nested property image
+list.
+
+See `versions/2.15.0/CHANGELOG.md` and `versions/2.15.0/MIGRATION.md`.
+
+### Legacy v9 Built-In Attributes
+
+From 2.14.0, built-in v9 property types and ordered option values come from the
+vOffice property catalog rather than example-value inference. The SDK keeps
+observed-only fields for compatibility, but examples do not redefine catalog
+fields.
+
+v9 `OPT` values are zero-based numeric indexes. The SDK resolves them to
+localized display text before adding them to `attributes`, `highlights`, or
+`vicinity`. For example:
+
+```text
+youthgroups = 0 → Jugendgruppen: willkommen
+youthgroups = 1 → Jugendgruppen: nicht erlaubt
+youthgroups = 2 → Jugendgruppen: auf Anfrage
+```
+
+An option index of `0` is a valid value, not Boolean `false`. Invalid,
+fractional, negative, and out-of-range indexes are omitted.
+
+Source-defined v9 `INT` values retain their numeric value, including `1`. Known
+count attributes use localized singular and plural nouns:
+
+```text
+bedrooms = 1 → 1 Schlafzimmer
+bedrooms = 2 → 2 Schlafzimmer
+bedrooms = 1 → 1 bedroom
+bedrooms = 2 → 2 bedrooms
+```
+
+Boolean behavior is unchanged: disabled values are omitted and enabled values
+are rendered as the localized label.
+
+Translation overrides use these key forms:
+
+```text
+RentalAttributes.<attribute>.label
+RentalAttributes.<attribute>.option.<zero-based-index>
+RentalAttributes.<attribute>.count.one
+RentalAttributes.<attribute>.count.other
+```
+
+See `versions/2.14.0/CHANGELOG.md` and
+`versions/2.14.0/MIGRATION.md`.
+
 ### Review Items
 
 Each review item contains at least `rating` or `text`. `id`, `author`, `label`, and `createdAt` are optional:

package/instructions/versions/2.14.0/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog: 2.14.0
+
+This release makes the vOffice v9 property catalog authoritative for built-in
+rental attribute types and option values. It fixes legacy option rendering,
+preserves numeric room counts of one, and improves the German and English
+attribute translations.
+
+## Added
+
+- Generated v9 property metadata now retains the source property type and every
+  ordered `OPT` value from the vOffice property export.
+- All 31 v9 `OPT` attributes have localized German and English option labels.
+- v9 option translations use stable numeric keys:
+
+  ```text
+  RentalAttributes.<attribute>.option.<zero-based-index>
+  ```
+
+- Count attributes can use localized singular and plural labels through:
+
+  ```text
+  RentalAttributes.<attribute>.count.one
+  RentalAttributes.<attribute>.count.other
+  ```
+
+- Property generation validates all 420 catalog fields, all 30 observed-only
+  compatibility fields, option-index ranges in the fixture corpus, and complete
+  option translation coverage.
+
+## Fixed
+
+- v9 `OPT` index `0` is no longer mistaken for a disabled Boolean value.
+- v9 `OPT` index `1` is no longer rendered as a bare Boolean-style label.
+- Higher option indexes are no longer rendered as quantities such as
+  `2 Jugendgruppen`.
+- `youthgroups` now maps its zero-based values correctly:
+  - `0`: `willkommen` / `welcome`
+  - `1`: `nicht erlaubt` / `not allowed`
+  - `2`: `auf Anfrage` / `on request`
+- Option rendering is consistent across rental attributes, highlights, and
+  vicinity output.
+- Numeric v9 `INT` attributes retain a value of `1`. For example, bedroom counts
+  now render as `1 Schlafzimmer` or `1 bedroom` instead of only the label.
+- Known count attributes use grammatically correct singular and plural forms.
+- German and English v9 rental, filter, and option copy has corrected grammar,
+  spelling, capitalization, punctuation, terminology, and unit formatting.
+- Corrected semantic translation errors, including German sea-view filtering
+  previously labeled as `Seeblick`.
+
+## Changed
+
+- Source-defined v9 property schemas no longer depend on whichever values happen
+  to occur in example fixtures. Examples remain inputs only for compatibility
+  fields absent from the catalog and for validation.
+- Invalid, fractional, negative, or out-of-range v9 option indexes are omitted
+  instead of being exposed as misleading display text.
+- English v9 rental type `FLAT` is now displayed as `Apartment`.
+- Official Spanish Modelo 179 terminology remains Spanish in both locales to
+  avoid changing legal and cadastral meanings.
+
+## Compatibility
+
+- No SDK construction, configuration, service-call, or public TypeScript shape
+  changes are required.
+- Existing Boolean behavior is unchanged: disabled values remain omitted and
+  enabled values remain label-only.
+- Existing custom attributes and observed-only v9 compatibility fields remain
+  supported.
+- Consumer snapshots, string comparisons, or UI tests that depend on the former
+  incorrect v9 strings must be updated.
+
+See `versions/2.14.0/MIGRATION.md` and `../../rentals.md`.

package/instructions/versions/2.14.0/MIGRATION.md

@@ -0,0 +1,148 @@
+# Migration: 2.13.0 to 2.14.0
+
+2.14.0 corrects presentation of built-in v9 rental attributes. The public SDK
+types and service calls are unchanged, but applications that snapshot, compare,
+filter, or parse localized attribute strings must account for corrected output.
+
+Consumers that use only v10 are not affected by the v9 parsing changes.
+
+## 1. Expect Correct v9 Option Labels
+
+Before 2.14.0, numeric v9 option indexes passed through Boolean and quantity
+heuristics. A `youthgroups` value could therefore produce:
+
+```text
+0 → omitted
+1 → Jugendgruppen
+2 → 2 Jugendgruppen
+```
+
+From 2.14.0, values resolve through the ordered vOffice option catalog:
+
+```text
+0 → Jugendgruppen: willkommen
+1 → Jugendgruppen: nicht erlaubt
+2 → Jugendgruppen: auf Anfrage
+```
+
+English output is equivalent:
+
+```text
+0 → Youth groups: welcome
+1 → Youth groups: not allowed
+2 → Youth groups: on request
+```
+
+This applies to all 31 built-in v9 option attributes and to every output surface
+that renders them:
+
+- rental `attributes`
+- rental `highlights`
+- rental `vicinity`
+
+Do not parse a visible option string back into an index. Treat these values as
+localized display text.
+
+## 2. Preserve Numeric Counts of One
+
+Before 2.14.0, the shared legacy renderer interpreted numeric `1` as Boolean
+`true`, so a bedroom count could be reduced to only its label.
+
+From 2.14.0, source-defined `INT` values remain numeric display values:
+
+```text
+1 Schlafzimmer
+2 Schlafzimmer
+1 bedroom
+2 bedrooms
+```
+
+Known count attributes use localized singular and plural nouns. Distance and
+square-meter formatting retain their specialized output.
+
+Update snapshots or UI assertions that expected a bare label for a count of one.
+
+## 3. Expect Corrected Translation Copy
+
+The v9 German and English catalogs have been proofread. Visible changes include:
+
+- corrected compound words, capitalization, punctuation, and unit notation
+- natural US English instead of generated key-like labels
+- corrected German terminology and post-1996 spelling
+- `Apartment` instead of `Flat` for the English v9 `FLAT` rental type
+- corrected filter labels such as German `Meerblick`
+
+Applications should render SDK output directly. Avoid branching on translated
+labels because wording can be corrected without changing an attribute's
+underlying meaning.
+
+## 4. Update Translation Overrides if Needed
+
+Attribute label overrides continue to use:
+
+```text
+RentalAttributes.<attribute>.label
+```
+
+v9 built-in option overrides use their zero-based source index:
+
+```text
+RentalAttributes.youthgroups.option.0
+RentalAttributes.youthgroups.option.1
+RentalAttributes.youthgroups.option.2
+```
+
+Count noun overrides can distinguish singular and plural:
+
+```text
+RentalAttributes.bedrooms.count.one
+RentalAttributes.bedrooms.count.other
+```
+
+Example:
+
+```ts
+const options = defineWebsiteSDKOptions({
+  translationOverrides: {
+    "en-US": {
+      "RentalAttributes.youthgroups.option.0": "Youth groups welcome",
+      "RentalAttributes.bedrooms.count.one": "sleeping room",
+      "RentalAttributes.bedrooms.count.other": "sleeping rooms",
+    },
+  },
+});
+```
+
+Do not reuse v10 named enum keys for v9 numeric options unless the application
+deliberately supplies both key forms.
+
+## 5. Invalid Option Values
+
+The parser accepts the numeric wire format used by v9, then resolves only finite
+integer indexes present in the catalog. Invalid, fractional, negative, and
+out-of-range values are omitted from display output.
+
+This preserves non-failing rental parsing while preventing unknown values from
+appearing as fabricated quantities.
+
+## Required Consumer Work
+
+No configuration or API migration is required. Check the following when the
+application consumes v9:
+
+1. Update snapshots and visual tests for corrected option and count strings.
+2. Remove code that compensates for missing option index `0`.
+3. Remove parsing or special casing for strings such as `2 Jugendgruppen`.
+4. Review translation overrides for corrected built-in copy.
+5. Verify room counts of one and two in both supported locales.
+6. Verify any configured option-valued highlight now displays its option label.
+
+## Recommended Verification
+
+1. Render `youthgroups` with values `0`, `1`, and `2`.
+2. Render `bedrooms` with values `1` and `2`.
+3. Confirm a Boolean value of `0` remains omitted and `1` remains label-only.
+4. Confirm a LOCATION option such as `beachtype` appears correctly in
+   `vicinity`.
+5. Confirm invalid option indexes do not appear.
+6. Run consumer snapshots in `de-DE` and `en-US`.

package/instructions/versions/2.15.0/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog: 2.15.0
+
+This release adds facility images to normalized v9 static rental output. v9
+consumers can now read responsive property images from the same
+`property.images` field already used by the shared rental contract.
+
+## Added
+
+- v9 static rentals request the facility `images` data attribute through the
+  existing GraphQL `all` query.
+- Parsed facility images are exposed under:
+
+  ```ts
+  rental.property?.images;
+  ```
+
+- Every mapped facility image includes:
+  - `idOrPath` from the vOffice image ID
+  - an `xl` fallback `src`
+  - a responsive width-descriptor `srcset`
+  - localized `alt` and `title` when a title is available
+  - `category` when vOffice supplies an image tag
+  - the original v9 image metadata under `metadata.dataImage`
+- The generated v9 facility-data schema recognizes facility image records and
+  validates them with the existing `ImageDataSchema`.
+- Facility `srcset` candidates use the unique vOffice dynamic-image presets:
+  `141w`, `225w`, `450w`, `600w`, `1440w`, and `2400w`. Candidates are capped
+  at the known original image width and duplicate widths are omitted.
+
+## Changed
+
+- v9 facility image bytes are served by the documented vOffice dynamic-image
+  origin:
+
+  ```text
+  https://dyn.v-office.com/image/<size>/<image-id>.jpg
+  ```
+
+- Facility images no longer need to be inferred from a rental image storage
+  path. That inference was invalid because facility image IDs are not present
+  in the v9 rental image rows.
+- A v9 property shared by several rentals carries the same facility image list
+  on each normalized rental's nested `property` object.
+
+## Unchanged
+
+- `sdk.static.rentals.getRentals({ locale })` and its input are unchanged.
+- The public `RentalPropertySchema` and image shape are unchanged because
+  `property.images` was already part of the shared contract.
+- Top-level v9 rental `images` continue to use the configured
+  `imageProxyBaseUrl`.
+- v10 rental and property image behavior is unchanged.
+- No new SDK configuration or environment variable is required.
+
+## Compatibility
+
+- This is an additive output change. v9 consumers that ignore
+  `property.images` do not need code changes.
+- Content Security Policy or image-host allowlists must permit
+  `https://dyn.v-office.com` before rendering the new v9 property images.
+- Snapshots that include complete v9 property objects must account for the new
+  optional `images` field.
+- Facility image entries without a numeric vOffice image ID are omitted because
+  no deterministic dynamic-image URL can be constructed.
+
+See `versions/2.15.0/MIGRATION.md` and `../../rentals.md`.

package/instructions/versions/2.15.0/MIGRATION.md

@@ -0,0 +1,148 @@
+# Migration: 2.14.0 to 2.15.0
+
+2.15.0 adds facility images to v9 static rental properties. The SDK call,
+configuration, and public TypeScript shape are unchanged, but complete v9
+property objects can now contain `images`.
+
+Consumers that use only v10 are not affected.
+
+## 1. Allow the vOffice Image Origin
+
+v9 facility image URLs use:
+
+```text
+https://dyn.v-office.com
+```
+
+Add that origin to image-host allowlists and Content Security Policy before
+rendering `property.images`. For example:
+
+```text
+Content-Security-Policy: img-src 'self' https://dyn.v-office.com
+```
+
+Top-level v9 rental images still use the configured `imageProxyBaseUrl`. A page
+that renders both image kinds must allow both origins.
+
+## 2. Read Facility Images from `property.images`
+
+No new service call is required:
+
+```ts
+const rentals = await sdk.static.rentals.getRentals({ locale: "de-DE" });
+
+for (const rental of rentals) {
+  for (const image of rental.property?.images ?? []) {
+    renderPropertyImage(image);
+  }
+}
+```
+
+The field remains optional. It is omitted when a rental has no facility, when
+the facility has no images, or when no facility image has a usable numeric ID.
+
+Example image:
+
+```json
+{
+  "idOrPath": "28458352",
+  "src": "https://dyn.v-office.com/image/xl/28458352.jpg",
+  "srcset": "https://dyn.v-office.com/image/tn/28458352.jpg 141w, https://dyn.v-office.com/image/tnx/28458352.jpg 225w, https://dyn.v-office.com/image/s/28458352.jpg 450w, https://dyn.v-office.com/image/m/28458352.jpg 600w, https://dyn.v-office.com/image/xl/28458352.jpg 1440w, https://dyn.v-office.com/image/xxl/28458352.jpg 2400w",
+  "alt": "Hauptansicht",
+  "title": "Hauptansicht",
+  "category": "buildingMain"
+}
+```
+
+## 3. Provide the Layout-Specific `sizes` Attribute
+
+The SDK provides `src` and `srcset`. The consuming UI must provide `sizes`
+because only the application knows the rendered layout:
+
+```tsx
+<img
+  src={image.src}
+  srcSet={image.srcset}
+  sizes="(max-width: 768px) 100vw, 50vw"
+  alt={image.alt ?? ""}
+/>
+```
+
+Do not copy that example `sizes` value blindly. Match it to the actual image
+width in the application's responsive layout.
+
+The fallback `src` uses the `xl` vOffice preset. Browsers that support `srcset`
+select an appropriate candidate using `srcset`, `sizes`, viewport width, and
+device pixel ratio.
+
+## 4. Keep Rental and Property Images Distinct
+
+The two image collections represent different entities:
+
+```ts
+rental.images; // images belonging to the rental/unit
+rental.property?.images; // images belonging to the facility/property
+```
+
+They also use different origins in v9:
+
+- `rental.images`: configured `imageProxyBaseUrl`
+- `rental.property.images`: `https://dyn.v-office.com`
+
+Do not merge the arrays unless the UI deliberately presents a combined gallery.
+Keeping them separate prevents facility images from being mistaken for
+unit-specific rooms or amenities.
+
+## 5. Account for Repeated Property Data
+
+The normalized rentals API returns one item per rental. When several rentals
+belong to the same facility, each rental contains the same nested property image
+list.
+
+Applications that build a property-level view can deduplicate by `property.id`:
+
+```ts
+const properties = new Map(
+  rentals.flatMap((rental) =>
+    rental.property == null ? [] : [[rental.property.id, rental.property] as const],
+  ),
+);
+```
+
+No separate property endpoint or persistence layer was added in 2.15.0.
+
+## 6. Update Snapshots and Complete-Object Assertions
+
+Tests that compare only selected property fields are unaffected. Tests that
+snapshot or deeply compare complete v9 rental output can now observe:
+
+```ts
+rental.property.images;
+```
+
+Update those expectations without making `property.images` mandatory. Backend
+facilities are allowed to have no usable images.
+
+## Required Consumer Work
+
+For applications that render v9 property images:
+
+1. Allow `https://dyn.v-office.com` in CSP and image-host configuration.
+2. Render `rental.property.images` separately from top-level rental images.
+3. Supply an HTML `sizes` value appropriate for the layout.
+4. Keep empty and missing image arrays valid.
+5. Update complete-output snapshots.
+
+Applications that do not render v9 property images require no migration work.
+
+## Recommended Verification
+
+1. Fetch v9 static rentals in both `de-DE` and `en-US`.
+2. Confirm facilities with images expose `property.images`.
+3. Confirm localized image titles populate `alt` and `title`.
+4. Confirm the browser selects responsive candidates after adding `sizes`.
+5. Confirm `dyn.v-office.com` is accepted by production CSP.
+6. Confirm top-level rental images still use the configured image proxy.
+7. Confirm a shared facility does not create duplicate property cards when the
+   application deduplicates by `property.id`.
+8. Confirm v10 rental and property image rendering remains unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v-office/website-sdk",
-  "version": "2.13.0",
+  "version": "2.15.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.13.0",
+    "@v-office/sdk-core": "^1.15.0",
     "effect": "4.0.0-beta.85",
     "graphql": "17.0.2",
     "yaml": "^2.9.0"
@@ -67,8 +67,9 @@
     "playground:parser": "node playground/query-parser.ts",
     "cli": "node --env-file=.env dist/cli.mjs",
     "build": "tsdown",
+    "codegen:v9:properties": "node codegen/v9/heuristic-generation/generate/index.ts && oxfmt codegen/v9/heuristic-generation/v9-data.ts",
     "codegen:v9:graphql": "graphql-codegen --config codegen/v9/graphql-codegen/codegen.ts",
-    "codegen": "pnpm run codegen:v9:graphql",
+    "codegen": "pnpm run codegen:v9:properties && pnpm run codegen:v9:graphql",
     "dev": "tsdown --watch",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint .",
@@ -76,7 +77,8 @@
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check",
     "check": "pnpm run typecheck && pnpm run lint && pnpm run fmt:check",
-    "test": "pnpm run build && node --test test/*.test.mjs",
+    "test": "pnpm run test:v9:properties && 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",
     "playground:custom-attributes": "pnpm run build && node --env-file=.env playground/custom-attributes.ts"
   }
 }