@v-office/website-sdk 2.12.0 → 2.14.0

package/instructions/versions/2.13.0/MIGRATION.md

@@ -0,0 +1,315 @@
+# Migration: 2.12.0 to 2.13.0
+
+2.13.0 introduces a breaking, shared booking-payment output for v9 and v10. The
+new model is intentionally presentation-oriented: labels, amounts, deadlines,
+payment locations, and breakdown lines are already translated and formatted for
+the booking locale.
+
+## 1. Replace the Flat Payment Schedule
+
+Before 2.13.0:
+
+```ts
+booking.paymentSchedules;
+```
+
+From 2.13.0:
+
+```ts
+booking.payment.schedule;
+booking.payment.alternatives;
+```
+
+`payment.schedule` contains contractual payment steps. `payment.alternatives`
+contains distinct alternatives such as paying the complete outstanding balance.
+
+Example:
+
+```json
+{
+  "bookingNumber": "B-2026-0001",
+  "payment": {
+    "schedule": [
+      {
+        "kind": "prepayment",
+        "label": "Anzahlung",
+        "amount": "76,00 €",
+        "dueOn": "Zahlbar bis zum 19. August 2026",
+        "paymentOptions": [
+          {
+            "kind": "bank_transfer",
+            "label": "Überweisung",
+            "holder": "Ferienvermietung Muster GmbH",
+            "iban": "DE02 1203 0000 0000 2020 51",
+            "remittanceText": "Buchungsnummer: B-2026-0001"
+          }
+        ]
+      },
+      {
+        "kind": "remaining_payment",
+        "label": "Restzahlung",
+        "amount": "304,00 €",
+        "dueOn": "Zahlbar bis zum 6. Februar 2027"
+      }
+    ],
+    "alternatives": [
+      {
+        "kind": "full_amount",
+        "label": "Gesamtzahlung",
+        "amount": "380,00 €",
+        "paymentOptions": [
+          {
+            "kind": "bank_transfer",
+            "label": "Überweisung",
+            "holder": "Ferienvermietung Muster GmbH",
+            "iban": "DE02 1203 0000 0000 2020 51",
+            "remittanceText": "Buchungsnummer: B-2026-0001"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## 2. Read `amount` Instead of `total`
+
+The old schedule-level `total` field has been renamed to `amount`:
+
+```ts
+for (const entry of booking.payment.schedule) {
+  renderAmount(entry.amount);
+}
+```
+
+The value remains a localized display string. Do not parse it for arithmetic or
+payment initiation.
+
+Optional `lines` continue to contain translated labels and formatted amounts:
+
+```ts
+for (const line of entry.lines ?? []) {
+  renderBreakdownLine(line.label, line.amount);
+}
+```
+
+## 3. Render Schedule and Alternative Entries
+
+To render every payment entry:
+
+```ts
+const paymentEntries = [...booking.payment.schedule, ...booking.payment.alternatives];
+
+for (const entry of paymentEntries) {
+  renderPaymentEntry(entry);
+}
+```
+
+Use the stable `kind` only for programmatic behavior. Use `label` for visible
+text.
+
+Schedule kinds:
+
+- `prepayment`: a named v9 down payment.
+- `remaining_payment`: a named v9 remaining payment.
+- `installment`: a v10 installment step.
+- `deposit`: a v10 deposit step.
+
+Alternative kinds:
+
+- `full_amount`: settle the complete currently outstanding balance.
+
+Do not infer v9 semantics from v10 step order. A v10 installment is not
+automatically a prepayment or remaining payment.
+
+## 4. Treat `paymentOptions` as Capability Data
+
+`paymentOptions` is optional on scheduled steps. Its absence means the entry is
+informational and is not currently payable through the SDK.
+
+```ts
+for (const option of entry.paymentOptions ?? []) {
+  if (option.kind === "bank_transfer") {
+    renderBankTransfer(option);
+  } else {
+    renderSubmitButton(() => sdk.live.booking.submitPaymentOption(option));
+  }
+}
+```
+
+Do not attach payment buttons to future, on-site, or external entries merely
+because they appear in `payment.schedule`.
+
+`full_amount` alternatives always contain a `paymentOptions` array. The array can
+be empty when the backend supplies no executable method.
+
+## 5. Render Dates and Payment Locations Directly
+
+Before 2.13.0, `dueOn` was locale-short text even though older documentation
+showed an ISO value. Consumers sometimes attempted to parse it as
+`YYYY-MM-DD`.
+
+From 2.13.0, `dueOn` is a complete localized phrase:
+
+```text
+Zahlbar bis zum 6. Februar 2027
+Payable until February 6, 2027
+```
+
+Render it directly:
+
+```ts
+if (entry.dueOn) renderSupportingText(entry.dueOn);
+if (entry.paymentAt) renderSupportingText(entry.paymentAt);
+```
+
+Do not prepend another due-date label and do not parse or reformat these fields.
+`paymentAt` is currently populated by v10 when payment-step location information
+is available.
+
+## 6. Account for the Corrected v9 Schedule
+
+Legacy v9 now emits both authoritative contractual steps:
+
+- `prepayment` with its own amount and deadline.
+- `remaining_payment` with its own amount and deadline.
+
+The `full_amount` alternative is separate. When the SDK synthesizes it from
+prepayment plus remaining payment, it has no deadline. The SDK no longer copies
+the prepayment deadline onto that alternative.
+
+Consequently, code must not derive a remaining-payment deadline from
+`payment.alternatives`.
+
+## 7. Account for the Expanded v10 Schedule
+
+v10 now preserves all remaining backend payment steps in
+`payment.schedule`, including:
+
+- `ONLINE`
+- `ON_SITE`
+- `EXTERN`
+
+Only the next eligible online step receives an initialized Adyen option. Later
+steps remain available as informational entries. The complete outstanding amount
+can appear separately under `payment.alternatives`.
+
+The alternative amount is the current outstanding balance, not necessarily the
+original booking total.
+
+## 8. Migrate Post-Booking Insurance
+
+Before 2.13.0:
+
+```ts
+await sdk.live.quote.bookInsurance({
+  quote,
+  bookingNumber: booking.bookingNumber,
+  guestToken: booking.guestToken,
+});
+```
+
+From 2.13.0:
+
+```ts
+await sdk.live.quote.bookInsurance({
+  quote,
+  booking,
+});
+```
+
+`guestToken` is no longer public. For v9, it is stored as private state on the
+opaque booking object and consumed internally by the SDK.
+
+Keep the same live booking object until insurance booking is complete:
+
+```ts
+const booking = await sdk.live.booking.book(input);
+
+// Do not JSON round-trip `booking` before this call.
+const insurance = await sdk.live.quote.bookInsurance({ quote, booking });
+```
+
+Spreading, serializing, reconstructing, or transferring the booking object loses
+its private backend context. If the application must cross a page reload or
+process boundary, complete insurance before that boundary.
+
+## 9. Update Payment-Option Selection
+
+Before 2.13.0:
+
+```ts
+const option = booking.paymentSchedules[0]?.paymentOptions.find(
+  (candidate) => candidate.kind !== "bank_transfer",
+);
+```
+
+From 2.13.0:
+
+```ts
+const option = [...booking.payment.schedule, ...booking.payment.alternatives]
+  .flatMap((entry) => entry.paymentOptions ?? [])
+  .find((candidate) => candidate.kind !== "bank_transfer");
+```
+
+Continue passing the selected structured option unchanged to
+`submitPaymentOption`.
+
+## 10. Handle Optional Insurance Output
+
+`insurancePaymentOptions` is omitted when no post-booking insurance payment is
+available:
+
+```ts
+for (const option of booking.insurancePaymentOptions ?? []) {
+  renderInsurancePaymentOption(option);
+}
+```
+
+This keeps v10 and bookings without selected insurance minimal.
+
+## 11. Replace Hardcoded Search Capability Tables
+
+This migration is optional and additive. Search UI that needs to decide which
+period controls to render can query backend support without constructing an SDK:
+
+```ts
+import {
+  getSupportedPeriodQueryKeys,
+  supportsFlexiblePeriodSearch,
+  type BackendKind,
+} from "@v-office/website-sdk/capabilities/search";
+
+const shouldRenderFlexiblePeriod = (backend: BackendKind) => supportsFlexiblePeriodSearch(backend);
+
+const supportedPeriodKeys = getSupportedPeriodQueryKeys("v9");
+supportedPeriodKeys.has("month"); // false
+```
+
+Remove local v9/v10 period-key tables in favor of these helpers. Both helpers are
+derived from the same core definitions used by SDK search parsing, so backend
+support changes do not require consumers to update a copied matrix.
+
+The returned `ReadonlySet` includes supported aliases such as `from`, `till`,
+`nights_min`, and `nights_max`. It describes individual key support; normal
+search validation still determines whether a complete combination of keys and
+values is executable.
+
+## Recommended Verification
+
+1. Book a v9 reservation with distinct prepayment and remaining-payment dates.
+2. Confirm both entries retain their own translated long-form deadline.
+3. Confirm a synthesized v9 `full_amount` alternative has no deadline.
+4. Confirm future v9 remaining payment has no payment button unless the SDK
+   supplies a payment option.
+5. Book a v10 reservation with multiple online and on-site/external payment steps.
+6. Confirm every remaining v10 step is rendered in backend order.
+7. Confirm only the next payable online step has an Adyen option.
+8. Confirm the full-payment alternative displays the outstanding balance without
+   an inferred deadline.
+9. Render both supported locales and verify all amounts, dates, locations, labels,
+   and breakdown lines are presentation-ready.
+10. Complete v9 insurance with the live booking object and verify the private
+    credential is not present in serialized output.
+11. If replacing a local search capability table, confirm flexible-period controls
+    remain hidden for v9 and visible for v10.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v-office/website-sdk",
-  "version": "2.12.0",
+  "version": "2.14.0",
   "description": "Website-facing SDK facade backed by @v-office/sdk-core",
   "bin": {
     "website-sdk": "./dist/cli.mjs"
@@ -33,6 +33,7 @@
   },
   "exports": {
     ".": "./dist/index.mjs",
+    "./capabilities/*": "./dist/capabilities/*.mjs",
     "./cli": "./dist/cli.mjs",
     "./package.json": "./package.json"
   },
@@ -41,7 +42,7 @@
   },
   "dependencies": {
     "@graphql-typed-document-node/core": "3.2.0",
-    "@v-office/sdk-core": "^1.12.0",
+    "@v-office/sdk-core": "^1.14.0",
     "effect": "4.0.0-beta.85",
     "graphql": "17.0.2",
     "yaml": "^2.9.0"
@@ -66,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 .",
@@ -75,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"
   }
 }