@v-office/website-sdk 2.28.1 → 2.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/README.md +8 -0
  2. package/dist/cli.mjs +406 -12
  3. package/dist/{client-EtS0Qm3i.mjs → client-CKVwzIQ4.mjs} +381 -53
  4. package/dist/index.d.mts +45 -6
  5. package/dist/index.mjs +1 -1
  6. package/dist/instructions/CHANGELOG.md +2 -0
  7. package/dist/instructions/MIGRATION.md +2 -0
  8. package/dist/instructions/README.md +3 -2
  9. package/dist/instructions/availability.md +22 -2
  10. package/dist/instructions/creation.md +35 -4
  11. package/dist/instructions/custom-attributes.md +2 -2
  12. package/dist/instructions/filter.md +5 -3
  13. package/dist/instructions/quote.md +1 -1
  14. package/dist/instructions/rentals.md +36 -0
  15. package/dist/instructions/search.md +220 -6
  16. package/dist/instructions/versions/2.29.0/CHANGELOG.md +62 -0
  17. package/dist/instructions/versions/2.29.0/MIGRATION.md +97 -0
  18. package/dist/instructions/versions/2.30.0/CHANGELOG.md +40 -0
  19. package/dist/instructions/versions/2.30.0/MIGRATION.md +30 -0
  20. package/dist/{v9-data-C3SWtDGs.mjs → operations-CfjJjdrw.mjs} +3122 -1
  21. package/dist/{rentals-B4g91vwW.mjs → rentals-cmqp5dTw.mjs} +4 -5
  22. package/dist/{search-B-lvOmXL.mjs → search-DPsBki_9.mjs} +6 -5
  23. package/dist/{to-rental-highlights-BL5m3Uen.mjs → to-rental-highlights-D7oepO6s.mjs} +1 -1
  24. package/dist/translations/v9/de-DE/core.json +8 -1
  25. package/dist/translations/v9/en-US/core.json +8 -1
  26. package/instructions/CHANGELOG.md +2 -0
  27. package/instructions/MIGRATION.md +2 -0
  28. package/instructions/README.md +3 -2
  29. package/instructions/availability.md +22 -2
  30. package/instructions/creation.md +35 -4
  31. package/instructions/custom-attributes.md +2 -2
  32. package/instructions/filter.md +5 -3
  33. package/instructions/quote.md +1 -1
  34. package/instructions/rentals.md +36 -0
  35. package/instructions/search.md +220 -6
  36. package/instructions/versions/2.29.0/CHANGELOG.md +62 -0
  37. package/instructions/versions/2.29.0/MIGRATION.md +97 -0
  38. package/instructions/versions/2.29.0/release.json +3 -0
  39. package/instructions/versions/2.30.0/CHANGELOG.md +40 -0
  40. package/instructions/versions/2.30.0/MIGRATION.md +30 -0
  41. package/instructions/versions/2.30.0/release.json +3 -0
  42. package/package.json +6 -4
  43. package/dist/operations-DwURbo0b.mjs +0 -2850
@@ -1,7 +1,6 @@
1
- import { Gt as V9_FACILITY_ATTRIBUTE_KEYS } from "./client-EtS0Qm3i.mjs";
2
- import { i as VofficeUnitDataPropertyMetadata, l as parseVofficeUnitData, n as VofficeUnitDataPropertyCategoryLabelKeys, o as parseVofficeFacilityData, r as VofficeUnitDataPropertyCategoryValues, s as parseVofficeFeedbackData, t as VofficeUnitDataFieldSchemas } from "./v9-data-C3SWtDGs.mjs";
3
- import { a as rentalsAllByFacilityObjectGroupsWithoutFeedbacksQuery, i as rentalIdsQuery, o as rentalsAllFeedbacksQuery, r as rentalFacilitiesForObjectGroupRelationQuery, s as rentalsAllWithoutFeedbacksQuery } from "./operations-DwURbo0b.mjs";
4
- import { a as toFacilityImages, c as toLocalizedString, i as toLocation, o as toImages, r as renderVofficePropertyAttribute, s as toAddress, t as toRentalHighlights } from "./to-rental-highlights-BL5m3Uen.mjs";
1
+ import { Yt as V9_FACILITY_ATTRIBUTE_KEYS } from "./client-CKVwzIQ4.mjs";
2
+ import { a as rentalFacilitiesForObjectGroupRelationQuery, c as rentalsAllFeedbacksQuery, d as VofficeUnitDataPropertyCategoryLabelKeys, f as VofficeUnitDataPropertyCategoryValues, g as parseVofficeFeedbackData, h as parseVofficeFacilityData, i as hubFiltersQuery, l as rentalsAllWithoutFeedbacksQuery, o as rentalIdsQuery, p as VofficeUnitDataPropertyMetadata, s as rentalsAllByFacilityObjectGroupsWithoutFeedbacksQuery, u as VofficeUnitDataFieldSchemas, v as parseVofficeUnitData } from "./operations-CfjJjdrw.mjs";
3
+ import { a as toFacilityImages, c as toLocalizedString, i as toLocation, o as toImages, r as renderVofficePropertyAttribute, s as toAddress, t as toRentalHighlights } from "./to-rental-highlights-D7oepO6s.mjs";
5
4
  import { CoreSDKError, makeTranslate, renderResolvedCustomAttribute, toCustomAttributeList, toResolvedCustomAttributeCategoryTranslationKey } from "@v-office/sdk-core";
6
5
  import { Effect } from "effect";
7
6
  //#region src/legacy-v9/parser/rentals/to-description.ts
@@ -585,4 +584,4 @@ const associateRentalsWithFacilitiesByObjectGroups = ({ attributeId, facilities,
585
584
  //#region src/legacy-v9/runtime/rentals.ts
586
585
  const defaultRentalDataAttributes = Object.keys(VofficeUnitDataFieldSchemas);
587
586
  //#endregion
588
- export { associateRentalsWithFacilitiesByObjectGroups, defaultRentalDataAttributes, rentalFacilitiesForObjectGroupRelationQuery, rentalIdsQuery, rentalsAllByFacilityObjectGroupsWithoutFeedbacksQuery, rentalsAllFeedbacksQuery, rentalsAllWithoutFeedbacksQuery, toRentalRentalsOutput };
587
+ export { associateRentalsWithFacilitiesByObjectGroups, defaultRentalDataAttributes, hubFiltersQuery, rentalFacilitiesForObjectGroupRelationQuery, rentalIdsQuery, rentalsAllByFacilityObjectGroupsWithoutFeedbacksQuery, rentalsAllFeedbacksQuery, rentalsAllWithoutFeedbacksQuery, toRentalRentalsOutput };
@@ -1,7 +1,6 @@
1
- import { a as parseQueryParameters, i as collectQueryParameters, n as makeV9CustomAttributeFilterCapabilities, o as toQueryString, r as toBasicQueryInputs, s as applyVofficeFilterDerivedBasicQueryInputs } from "./client-EtS0Qm3i.mjs";
2
- import { l as parseVofficeUnitData } from "./v9-data-C3SWtDGs.mjs";
3
- import { n as searchQuery, t as mapSearchQuery } from "./operations-DwURbo0b.mjs";
4
- import { i as toLocation, n as toV9RentalHighlightKey, o as toImages, s as toAddress, t as toRentalHighlights } from "./to-rental-highlights-BL5m3Uen.mjs";
1
+ import { a as makeV9CustomAttributeFilterCapabilities, c as parseQueryParameters, d as toVoucherCode, l as toQueryString, o as toBasicQueryInputs, s as collectQueryParameters, u as applyVofficeFilterDerivedBasicQueryInputs } from "./client-CKVwzIQ4.mjs";
2
+ import { n as mapSearchQuery, r as searchQuery, v as parseVofficeUnitData } from "./operations-CfjJjdrw.mjs";
3
+ import { i as toLocation, n as toV9RentalHighlightKey, o as toImages, s as toAddress, t as toRentalHighlights } from "./to-rental-highlights-D7oepO6s.mjs";
5
4
  import { CoreSDKError, STABLE_SEARCH_INPUTS, daysBetweenLocalDates, expandCustomAttributeFilterCompositions, parseChildrenAges, parseOccupancyCount, resolveExpandedCompositions, toFormattedSearchPrice, toIsoDateFromPeriodQueryDate, toStableSearchInputBackendQueryKeys, toStableSearchInputParameterValues, toStableSearchInputQueryKeys, toUnusedFilterKeys } from "@v-office/sdk-core";
6
5
  import { Effect } from "effect";
7
6
  //#region src/legacy-v9/parser/search/input/search-input-error.ts
@@ -181,7 +180,7 @@ const toVofficeSorting = (sort) => {
181
180
  };
182
181
  //#endregion
183
182
  //#region src/legacy-v9/parser/search/input/to-query-input.ts
184
- const toQueryInput = ({ query, sort, customAttributeFilterDefinitions, locale, translations }) => Effect.gen(function* () {
183
+ const toQueryInput = ({ query, sort, voucher, customAttributeFilterDefinitions, locale, translations }) => Effect.gen(function* () {
185
184
  if (hasUnsupportedFlexiblePeriodInput(query)) return yield* failInvalidV9SearchInput("Legacy v9 search does not support flexible period query parameters \"month\", \"dates\", \"nights\", or \"weekend\". Use \"start\" and \"end\" for a fixed period.");
186
185
  const compositionResult = expandCustomAttributeFilterCompositions({
187
186
  capabilities: makeV9CustomAttributeFilterCapabilities(customAttributeFilterDefinitions),
@@ -218,11 +217,13 @@ const toQueryInput = ({ query, sort, customAttributeFilterDefinitions, locale, t
218
217
  ...toUnusedFilterKeys(basicQueryResult.remainingQuery)
219
218
  ]
220
219
  });
220
+ const voucherCode = toVoucherCode(voucher);
221
221
  return {
222
222
  appliedFilters: [...compositionFilters.appliedFilters, ...appliedFilters],
223
223
  queryInput: {
224
224
  vofficeData: {
225
225
  filter: Object.keys(filter).length > 0 ? filter : void 0,
226
+ ...voucherCode === void 0 ? {} : { voucherCode },
226
227
  alternatives: true,
227
228
  splitAlternatives: true,
228
229
  sorting: toVofficeSorting(sort)
@@ -1,4 +1,4 @@
1
- import { i as VofficeUnitDataPropertyMetadata } from "./v9-data-C3SWtDGs.mjs";
1
+ import { p as VofficeUnitDataPropertyMetadata } from "./operations-CfjJjdrw.mjs";
2
2
  import { localeToLanguage, makeTranslate, renderLabeledAttributeValue, renderResolvedCustomAttribute, toCountry } from "@v-office/sdk-core";
3
3
  import { Effect } from "effect";
4
4
  //#region src/legacy-v9/parser/rentals/to-localized-string.ts
@@ -8,5 +8,12 @@
8
8
  "Property.propertyType.option.HOSTEL": "Hostel",
9
9
  "Property.propertyType.option.HOTEL": "Hotel",
10
10
  "reviews.item.guest": "Gast",
11
- "reviews.item.authorWithCity": "{author} aus {city}"
11
+ "reviews.item.authorWithCity": "{author} aus {city}",
12
+ "voucher.validate.reason.valid": "Der Gutscheincode ist gültig.",
13
+ "voucher.validate.reason.not_yet_valid": "Der Gutscheincode ist noch nicht gültig.",
14
+ "voucher.validate.reason.expired": "Der Gutscheincode ist abgelaufen.",
15
+ "voucher.validate.reason.unknown": "Dieser Gutscheincode ist unbekannt.",
16
+ "voucher.validate.reason.stay_too_short": "Der Aufenthalt ist für diesen Gutscheincode zu kurz.",
17
+ "voucher.validate.reason.outside_booking_window": "Der gewählte Anreisetag liegt außerhalb des Buchungszeitraums dieses Gutscheincodes.",
18
+ "voucher.validate.reason.rate_limited": "Zu viele Versuche. Bitte versuchen Sie es später erneut."
12
19
  }
@@ -8,5 +8,12 @@
8
8
  "Property.propertyType.option.HOSTEL": "Hostel",
9
9
  "Property.propertyType.option.HOTEL": "Hotel",
10
10
  "reviews.item.guest": "Guest",
11
- "reviews.item.authorWithCity": "{author} from {city}"
11
+ "reviews.item.authorWithCity": "{author} from {city}",
12
+ "voucher.validate.reason.valid": "The voucher code is valid.",
13
+ "voucher.validate.reason.not_yet_valid": "The voucher code is not valid yet.",
14
+ "voucher.validate.reason.expired": "The voucher code has expired.",
15
+ "voucher.validate.reason.unknown": "This voucher code is unknown.",
16
+ "voucher.validate.reason.stay_too_short": "The stay is too short for this voucher code.",
17
+ "voucher.validate.reason.outside_booking_window": "The selected arrival date is outside this voucher code's booking window.",
18
+ "voucher.validate.reason.rate_limited": "Too many attempts. Please try again later."
12
19
  }
@@ -4,6 +4,8 @@
4
4
 
5
5
  Release notes of `@v-office/website-sdk`, newest first. Each version has its own directory.
6
6
 
7
+ - `versions/2.30.0/CHANGELOG.md`: release notes for 2.30.0
8
+ - `versions/2.29.0/CHANGELOG.md`: release notes for 2.29.0
7
9
  - `versions/2.28.1/CHANGELOG.md`: release notes for 2.28.1
8
10
  - `versions/2.28.0/CHANGELOG.md`: release notes for 2.28.0
9
11
  - `versions/2.27.0/CHANGELOG.md`: release notes for 2.27.0
@@ -4,6 +4,8 @@
4
4
 
5
5
  Migration guides of `@v-office/website-sdk`, newest first. Apply them in order when skipping versions.
6
6
 
7
+ - `versions/2.30.0/MIGRATION.md`: Migration: 2.29.0 to 2.30.0
8
+ - `versions/2.29.0/MIGRATION.md`: Migration: 2.28.1 to 2.29.0
7
9
  - `versions/2.28.1/MIGRATION.md`: Migration: 2.28.0 to 2.28.1
8
10
  - `versions/2.28.0/MIGRATION.md`: Migration: 2.27.0 to 2.28.0
9
11
  - `versions/2.27.0/MIGRATION.md`: Migration: 2.26.0 to 2.27.0
@@ -7,10 +7,10 @@ workflow performs the coordinated core and website bumps.
7
7
  Use this directory as the consumer-facing reference for the package:
8
8
 
9
9
  - `creation.md`: SDK construction, config, options, and CLI config files.
10
- - `rentals.md`: `sdk.static.rentals.getRentals`.
10
+ - `rentals.md`: `sdk.static.rentals.getRentals` and, on v9, `sdk.live.rentals.getRentalsByIds`.
11
11
  - `filter.md`: `sdk.static.filter.getFilters`.
12
12
  - `custom-attributes.md`: custom attribute catalog, configuration, per-backend behaviour, and the v9-to-v10 move.
13
- - `search.md`: `sdk.live.search.search` and, on v9, `sdk.live.search.searchPages`.
13
+ - `search.md`: `sdk.live.search.search`, vouchers, and, on v9, `sdk.live.search.searchPages`, Hub filters, and `sdk.live.voucher.validate`.
14
14
  - `availability.md`: date-picker availability flows.
15
15
  - `quote.md`: quote booking-card modifiers, additional services, cancellation policy, and insurance flows.
16
16
  - `booking.md`: booking, payment option submission, and
@@ -110,6 +110,7 @@ website-sdk --backend v10 rentals --locale de-DE
110
110
  website-sdk --backend v9 filters --locale en-US
111
111
  website-sdk --backend v10 search --locale de-DE --query "adults=2"
112
112
  website-sdk --backend v10 search --locale de-DE --query "adults=2" --sort '{"by":"field","orderBy":{"label":"ASC"}}'
113
+ website-sdk --backend v9 hub-filters request --object-group
113
114
  ```
114
115
 
115
116
  Config file examples in these docs use the flat `WebsiteSDKConfig` shape introduced
@@ -107,9 +107,9 @@ From 2.18.0, available dates that cannot be used as a start date also expose a
107
107
  price when the source supplies one. The same rule applies to v10 initial
108
108
  availability. `formattedPrice` remains `null` when the date is unavailable or
109
109
  the source supplies no numeric price.
110
- Start-date-selected availability does not include calendar prices.
110
+ v10 start-date-selected availability does not include calendar prices.
111
111
 
112
- When no successful unit lookup is cached, a v9 initial-availability request loads
112
+ When no successful unit lookup is cached, a v9 availability request loads
113
113
  the calendar and a unit record. Successful unit responses are cached by unit ID
114
114
  for the lifetime of the SDK instance, including responses without a currency.
115
115
  Failed unit requests are not cached and are retried on the next call. A missing
@@ -122,6 +122,26 @@ No new configuration is required. The currency lookup uses the existing
122
122
  See `versions/2.18.0/CHANGELOG.md` and
123
123
  `versions/2.18.0/MIGRATION.md`.
124
124
 
125
+ ### Legacy v9 Prices by Length of Stay
126
+
127
+ From 2.30.0, v9 calendar prices follow the rental's rates by number of nights.
128
+ Each night is priced by its own season, as the quote does.
129
+
130
+ - `getInitialAvailability` prices each day at the rate for the minimum stay
131
+ that applies from that day.
132
+ - `getStartDateSelectedAvailability` returns `formattedPrice` on every day
133
+ (`V9StartDateSelectedAvailabilityOutput`). On a day that can be the end date
134
+ it is the price of the last night of a stay from the selected start date to
135
+ that day, at the rate for that number of nights. On all other days it is
136
+ `null`.
137
+
138
+ When the rental's price list cannot be loaded or has no rate for a day, both
139
+ calls use the calendar price described above. The price list is cached per
140
+ rental for five minutes for the lifetime of the SDK instance.
141
+
142
+ See `versions/2.30.0/CHANGELOG.md` and
143
+ `versions/2.30.0/MIGRATION.md`.
144
+
125
145
  ### Legacy v9 Occupancy Limits
126
146
 
127
147
  From 2.28.0, v9 initial availability reads its occupancy limits from the same
@@ -49,10 +49,21 @@ const sdk = createWebsiteSDK({
49
49
  imageProxyBaseUrl: "https://images.example.com",
50
50
  rentalDataAttributes: ["name", "description"],
51
51
  facilityObjectGroupRelationAttributeId: 18962,
52
+ rentalScopePropertyKind: "objectGroup",
52
53
  },
53
54
  });
54
55
  ```
55
56
 
57
+ `rentalScopePropertyKind` is an optional v9-only setting that says what
58
+ `rentalScope.propertyId` names: `"facility"` (the default), a facility, or
59
+ `"objectGroup"`, a vOffice object group. It does not change `rental.property`, which
60
+ is always a facility. See [Rental Scope](#rental-scope).
61
+
62
+ `rentalIdsSearch` is an optional v9-only setting, `false` by default. With `true`, v9
63
+ search accepts `rentalIdsIn` (for example a favourites search). It needs the Hub
64
+ filter `voffice_id`; see
65
+ [v9: Favourites As A Search Filter](search.md#v9-favourites-as-a-search-filter).
66
+
56
67
  `facilityObjectGroupRelationAttributeId` is an optional v9-only compatibility
57
68
  setting for tenants whose units are associated with facilities through vOffice
58
69
  object groups instead of the native facility relation. Its numeric value `N`
@@ -193,8 +204,22 @@ const options = defineWebsiteSDKOptions({
193
204
 
194
205
  `propertyId` is a unified SDK option:
195
206
 
196
- - `v9` static rentals are filtered by `voffice_facility_id`.
197
- - `v9` live search maps it to the generated `VofficeFilter.falicityid` field.
207
+ - `v9` follows the config `rentalScopePropertyKind`:
208
+ - `"facility"` or unset: `propertyId` is the facility ID that `rental.property.id`
209
+ shows. Static rentals are filtered by it.
210
+ - `"objectGroup"`: `propertyId` is a vOffice object group ID. Static rentals keep
211
+ the members of the group.
212
+ - Search, `searchPages` and `mapSearch` apply the scope through the Hub filter
213
+ `facility_scope` or `objectGroup_scope`, with and without a period. The static
214
+ `getRentals` fails the build until the be-on! Hub has that entry, and names the
215
+ missing key. Run `website-sdk hub-filters request`; the user adds the entries in
216
+ the be-on! Hub, see [v9: Hub Filters](search.md#v9-hub-filters).
217
+ - `getRentals` fails the build for a facility scope next to
218
+ `facilityObjectGroupRelationAttributeId`: the listings would use the facilities
219
+ derived from object groups, the search the facility stored on each rental. If the
220
+ facilities are maintained on the rentals in vOffice, remove
221
+ `facilityObjectGroupRelationAttributeId`; otherwise scope by `"objectGroup"`.
222
+ - `propertyId` must be a positive decimal integer up to 2147483647.
198
223
  - `v10` static rentals and live search map it to the generated `rentals_RentalSummaryFilter.propertyId` field.
199
224
 
200
225
  The scope is always applied internally and is not returned by `static.filter.getFilters(...)`. Use it for website-level or tenant-level constraints.
@@ -262,8 +287,9 @@ Supported sources:
262
287
  active backend, and no generated leaf is committed unless all leaves are valid.
263
288
  Nested compositions are rejected while recursive expansion is unsupported.
264
289
 
265
- For a new v9 `backendFilter` key, ask someone at be-on! with Hub access to add or
266
- confirm the backend filter before configuring it in the SDK.
290
+ For a new v9 `backendFilter` key, the Hub filter must exist first; see
291
+ [v9: Hub Filters](search.md#v9-hub-filters). The keys `voffice_id`, `facility_scope` and
292
+ `objectGroup_scope` belong to the SDK: a v9 `backendFilter` cannot use them.
267
293
 
268
294
  Exposure:
269
295
 
@@ -309,6 +335,11 @@ Example `website-sdk-config.v10.json`:
309
335
  }
310
336
  ```
311
337
 
338
+ With environment configuration, the CLI reads the v9 settings `rentalScopePropertyKind`
339
+ and `rentalIdsSearch` from the optional `HUB_RENTAL_SCOPE_PROPERTY_KIND`
340
+ (`facility` or `objectGroup`) and `HUB_RENTAL_IDS_SEARCH` (`true` or `false`). Without
341
+ them, it treats a rental scope as a facility scope and keeps `rentalIdsIn` off.
342
+
312
343
  Example `website-sdk-options.json`:
313
344
 
314
345
  ```json
@@ -390,8 +390,8 @@ These are **not** custom attributes and stay in `customAttributeFilterDefinition
390
390
  backend with its configured value.
391
391
 
392
392
  Compositions may reference stable v9 built-ins directly; `backendFilter` is only for
393
- additional v9 keys. SDK configuration does not create those keys in Hub; ask someone
394
- at be-on! with Hub access to add or confirm the filter before configuring it.
393
+ additional v9 keys. SDK configuration does not create those keys in Hub: they are added
394
+ there first; see [v9: Hub Filters](search.md#v9-hub-filters).
395
395
 
396
396
  ```ts
397
397
  const options = defineWebsiteSDKOptions({
@@ -120,9 +120,11 @@ when it has a public filter and the selected backend can execute it. v9 has no
120
120
  custom-attribute search path, so v9 never advertises one; see `custom-attributes.md`.
121
121
 
122
122
  Backend filters and compositions come from `customAttributeFilterDefinitions`.
123
- SDK configuration cannot create a Hub filter: for another v9 key, first ask someone
124
- at be-on! with Hub access to add or confirm it, then configure that key as a
125
- `backendFilter`.
123
+ SDK configuration cannot create a Hub filter: for another v9 key, the entry is added
124
+ to the be-on! Hub first, then you configure that key as a `backendFilter`. Without
125
+ the Hub entry, the filter does nothing. See [v9: Hub Filters](search.md#v9-hub-filters)
126
+ for the fixed keys (object group, facility, special offers) and for
127
+ `website-sdk hub-filters request`.
126
128
 
127
129
  ```json
128
130
  {
@@ -62,7 +62,7 @@ Sample:
62
62
  ```
63
63
 
64
64
  Dates are local dates formatted as `YYYY-MM-DD`. For `v9`, `rentalId` must be a numeric vOffice unit id.
65
- Both backends accept `voucher` on quote and booking flows. On `v10`, applied voucher and non-voucher modifiers can be exposed through the booking-card fields described below. `v9` reflects voucher effects in quoted totals but does not expose booking-card modifier details.
65
+ Both backends accept `voucher` on quote and booking flows. On `v9`, `sdk.live.voucher.validate` checks a code before the quote; see [Vouchers](search.md#vouchers). On `v10`, applied voucher and non-voucher modifiers can be exposed through the booking-card fields described below. `v9` reflects voucher effects in quoted totals but does not expose booking-card modifier details.
66
66
 
67
67
  ## Output
68
68
 
@@ -10,6 +10,8 @@ const rentals = await sdk.static.rentals.getRentals({ locale: "de-DE" });
10
10
 
11
11
  The service is implemented for both `v9` and `v10` backends and returns one normalized item per rental.
12
12
 
13
+ On v9, `getRentals` fails when the site sets a rental scope or `rentalIdsSearch: true` and the be-on! Hub lacks the filter the search needs. The error names the missing key; see [Rental Scope](creation.md#rental-scope). For a favourites page, use `sdk.live.rentals.getRentalsByIds` (see [Legacy v9 Rentals By ID](#legacy-v9-rentals-by-id)).
14
+
13
15
  ## Input
14
16
 
15
17
  ```ts
@@ -211,6 +213,14 @@ several facilities fail the static rentals request instead of selecting an
211
213
  arbitrary property. The request also fails when no facility has a usable
212
214
  configured relation value.
213
215
 
216
+ A facility `rentalScope` does not work with this mode: the listings would use
217
+ the facilities derived from object groups, while the search filters by the
218
+ facility stored on each unit. `getRentals` fails the build for that
219
+ combination. If the facilities are maintained on the units in vOffice, remove
220
+ `facilityObjectGroupRelationAttributeId`. Otherwise set
221
+ `rentalScopePropertyKind: "objectGroup"` and use the object group ID as
222
+ `rentalScope.propertyId`.
223
+
214
224
  The relation attribute may contain positive numeric IDs as numbers, strings,
215
225
  localized string records, arrays, or strings separated by whitespace, commas,
216
226
  or semicolons. The association is locale-independent. The configured GraphQL
@@ -419,6 +429,26 @@ A feedback with neither rating nor text is never an item. `summary.rating` and
419
429
  covers the included items. When no included item has a rating, `reviews` has
420
430
  `items` and no `summary`. A text answer to a `text` criterion counts as text.
421
431
 
432
+ ## Legacy v9 Rentals By ID
433
+
434
+ `sdk.live.rentals.getRentalsByIds` loads the rentals with the given IDs, for example the
435
+ favourites a visitor saved in the browser. It needs no Hub entry, and it is v9 only:
436
+
437
+ ```ts
438
+ const rentalIds: string[] = JSON.parse(localStorage.getItem("favoredRentalIDs") ?? "[]");
439
+
440
+ const rentals = await sdk.live.rentals.getRentalsByIds({ locale: "de-DE", rentalIds });
441
+ ```
442
+
443
+ - It returns the same items as `getRentals`, reviews included.
444
+ - The result keeps the order of `rentalIds` and drops duplicates.
445
+ - An ID that is unknown, not a positive whole number, or outside the rental scope is
446
+ left out without an error. The browser may hold IDs of rentals that no longer exist.
447
+ - An empty list returns an empty array.
448
+
449
+ To combine favourites with the search filters, see
450
+ [v9: Favourites As A Search Filter](search.md#v9-favourites-as-a-search-filter).
451
+
422
452
  ## Configuration
423
453
 
424
454
  `v9` config:
@@ -531,6 +561,12 @@ website-sdk --backend v9 rentals --locale en-US
531
561
  website-sdk --backend v10 rentals --locale de-DE
532
562
  ```
533
563
 
564
+ Fetch v9 rentals by ID:
565
+
566
+ ```sh
567
+ website-sdk --backend v9 rentals-by-ids --locale en-US --rental-ids 12,34
568
+ ```
569
+
534
570
  Use files instead of environment variables:
535
571
 
536
572
  ```sh
@@ -11,7 +11,7 @@ const result = await sdk.live.search.search({
11
11
  });
12
12
  ```
13
13
 
14
- The service is implemented for both `v9` and `v10` backends and returns normalized rental result items. Filtering by `rentalIdsIn` is currently implemented for `v10` only.
14
+ The service is implemented for both `v9` and `v10` backends and returns normalized rental result items. On v9, `rentalIdsIn` is opt-in; see [v9: Favourites As A Search Filter](#v9-favourites-as-a-search-filter).
15
15
 
16
16
  ## Input
17
17
 
@@ -76,6 +76,7 @@ Common stable query keys:
76
76
  - Period: `start`, `end`, `from`, `till`, `minNights`, `maxNights`; date values support `DD-MM-YYYY` and `YYYY-MM-DD`; `v10` also supports `month`, `dates`, `nights`, and `weekend`.
77
77
  - Occupancy: `adults`, `children`, `childrenAges`, `babies`, `pets`, `petsCount`.
78
78
  - Filters: use `searchParameterQueryKey` values from `sdk.static.filter.getFilters(...)`.
79
+ - v9 filters beyond the built-in ones need a Hub entry; see [v9: Hub Filters](#v9-hub-filters).
79
80
 
80
81
  ### Static Backend Capabilities
81
82
 
@@ -175,6 +176,171 @@ Boolean filters can be provided as presence-only flags when supported:
175
176
  "wifi&bbq=true";
176
177
  ```
177
178
 
179
+ ### v9: Hub Filters
180
+
181
+ Legacy v9 searches through the be-on! Hub. The built-in filters listed in `filter.md`
182
+ work without setup. Every other filter, such as an object group or a special offer,
183
+ needs an entry in the Hub for the site's be-on key (`apiKey`). The SDK cannot create
184
+ that entry; the user adds it in the be-on! Hub. Until it exists, the filter silently does
185
+ nothing:
186
+
187
+ - A key the Hub does not know, alone and without `start`/`end` or guests, returns no
188
+ rentals.
189
+ - With a period, it returns every available rental.
190
+ - Next to another active filter, it is ignored.
191
+
192
+ So never configure a `backendFilter` before its Hub entry exists. A repeated key is
193
+ evaluated by the Hub once, with its first value; the SDK sends one value per key and
194
+ lists a repeated key in `unusedFilterKeys`.
195
+
196
+ #### Fixed Keys
197
+
198
+ The CLI requests these keys. Use them as they are.
199
+
200
+ | Key | Purpose | Value |
201
+ | --------------------------------------------------- | ------------------------------------------------------------- | ------------------------ |
202
+ | `objectGroup` | filter by object group | vOffice object group ID |
203
+ | `facility_search` | filter by facility | vOffice facility ID |
204
+ | `offers` | rentals with any special offer; the key must be `offers` | flag |
205
+ | `offer` | rentals linked to one special offer, without a validity check | vOffice offer ID |
206
+ | `facility_scope`, `objectGroup_scope`, `voffice_id` | set by the SDK for the rental scope and `rentalIdsIn` | none, never configure it |
207
+
208
+ Creating a v9 SDK throws when a `backendFilter` uses `facility_scope`,
209
+ `objectGroup_scope` or `voffice_id`. Rename such a definition. No other key is
210
+ reserved.
211
+
212
+ #### Requesting Hub Filters
213
+
214
+ When a user asks for one of these filters, run the CLI. It reads the Hub filters of the
215
+ be-on key, writes a Markdown file with the code to paste into the be-on! Hub and the
216
+ steps to do it, and prints the matching `backendFilter` definitions:
217
+
218
+ ```sh
219
+ website-sdk --backend v9 --config ./website-sdk-config.json hub-filters request --object-group --offers
220
+ ```
221
+
222
+ Flags: `--object-group`, `--facility`, `--offers`, `--offer`, `--unit` (the filter by
223
+ vOffice unit ID, see [v9: Favourites As A Search Filter](#v9-favourites-as-a-search-filter)),
224
+ and `--out <file>` (default `hub-filter-request.md`). A rental scope and
225
+ `rentalIdsSearch: true` add their keys to the request. The CLI reads the rental scope
226
+ from `--options` and the two settings from `--config` or, with environment
227
+ configuration, from `HUB_RENTAL_SCOPE_PROPERTY_KIND` and `HUB_RENTAL_IDS_SEARCH`.
228
+ Without a flag and without such a setting, or when the Hub already has every
229
+ requested key, it writes no file.
230
+
231
+ Show the user the steps and the code from the file; they paste the code into the
232
+ be-on! Hub themselves. The code is the complete content of the be-on key's filter
233
+ field and assumes the field is empty. If the field already holds entries, the user
234
+ hands the file to a developer, who merges them. Do not write Hub entries by hand.
235
+ Once the user has saved the entries, check them:
236
+
237
+ ```sh
238
+ website-sdk --backend v9 --config ./website-sdk-config.json --options ./website-sdk-options.json hub-filters check
239
+ ```
240
+
241
+ `hub-filters check` compares every configured `backendFilter` key, the scope key and
242
+ `voffice_id` (when `rentalIdsSearch` is on) with the Hub. It exits non-zero and names
243
+ the missing keys, with the `hub-filters request` flags for the fixed ones. A custom
244
+ key outside the fixed ones has no request flag: the SDK does not know which rental
245
+ field it compares, so a developer adds its entry by hand. The check sees only that a
246
+ key exists, not whether its entry is complete. When it passes, delete the request
247
+ file.
248
+
249
+ #### A Filter By Object Group
250
+
251
+ `objectGroup` keeps rentals in one vOffice object group. Use it when the agency sorts
252
+ its rentals into groups in vOffice, for example by location ("Am Strand") or by
253
+ property. It knows nothing but the group membership: a rental in the group always
254
+ matches, whatever the group is called. It does not limit the search to the site's
255
+ rentals; that is the rental scope's job (see `creation.md`).
256
+
257
+ Ask the user which object groups the filter offers. Request `--object-group`, then
258
+ add the printed definition with one option per group. The Hub returns IDs, no
259
+ names: the labels are the group names, and the site keeps them.
260
+
261
+ ```ts
262
+ {
263
+ key: "objectGroup",
264
+ source: "backendFilter",
265
+ category: "OTHER",
266
+ label: { "de-DE": "Lage", "en-US": "Location" },
267
+ type: "option",
268
+ options: [
269
+ { value: "20748", label: { "de-DE": "Am Hafen", "en-US": "At the harbour" } },
270
+ { value: "20747", label: { "de-DE": "Am Strand", "en-US": "At the beach" } },
271
+ ],
272
+ searchable: true,
273
+ internal: false,
274
+ }
275
+ ```
276
+
277
+ `getFilters` and `appliedFilters` show the labels. The filter works with and without a
278
+ period or guests and combines with a rental scope as AND. A visitor picks one group at
279
+ a time.
280
+
281
+ #### A Filter By Facility
282
+
283
+ `facility_search` keeps rentals of one facility (Ferienanlage), for a facility select
284
+ in the search. It only finds rentals whose facility is stored on the rental in vOffice.
285
+ A site that sets `facilityObjectGroupRelationAttributeId` links rentals to facilities
286
+ through object groups instead; there the filter matches nothing, so offer the object
287
+ groups with `objectGroup`.
288
+
289
+ Request `--facility`. Its values are vOffice facility IDs, not `rental.property.id`,
290
+ which is a different ID, so do not build filter links from `rental.property.id`. Once
291
+ the Hub entry exists, the CLI prints the definition with the options (ID and name) the
292
+ Hub knows. The English labels are the German names; translate them.
293
+
294
+ #### Special Offers
295
+
296
+ - `offers` keeps rentals with any special offer that vOffice shows to websites. With a
297
+ period, the Hub also asks vOffice whether the offer applies to it. Use it for a
298
+ "special offers only" checkbox or a page listing all deals. Request `--offers`.
299
+ - `offer` keeps rentals linked to one special offer, by vOffice offer ID. Use it for a
300
+ page about one campaign, for example an early-booking deal. It checks neither whether
301
+ the offer is shown to websites nor whether it applies to the requested period, so a
302
+ rental can match after its offer has ended. When the question is "which rentals have
303
+ a deal right now", use `offers`. Request `--offer`.
304
+
305
+ `offers` is a `boolean` definition and `offer` an `int` definition with the offer ID:
306
+
307
+ ```ts
308
+ "start=20-06-2026&end=27-06-2026&adults=2&offers";
309
+ "adults=2&offer=4711";
310
+ ```
311
+
312
+ v10 does not advertise or execute `backendFilter` definitions.
313
+
314
+ ### v9: Favourites As A Search Filter
315
+
316
+ For a favourites page, use `sdk.live.rentals.getRentalsByIds` (see `rentals.md`). It
317
+ needs no Hub entry. Use the search only when favourites must combine with the
318
+ other search filters, for example "favourites available in this period".
319
+
320
+ On v9, `rentalIdsIn` is off by default: a search with `rentalIdsIn` throws, even an
321
+ empty array. Offer it to the user once and ask whether they want favourites as a
322
+ search filter. If yes, set `rentalIdsSearch: true` in the v9 config and request the
323
+ Hub filter with `hub-filters request --unit`. The static `getRentals` then fails the
324
+ build until the Hub filter `voffice_id` exists.
325
+
326
+ ```ts
327
+ const favoredRentalIds: string[] = JSON.parse(localStorage.getItem("favoredRentalIDs") ?? "[]");
328
+
329
+ if (favoredRentalIds.length > 0) {
330
+ const result = await sdk.live.search.search({
331
+ locale: "de-DE",
332
+ query: "start=20-06-2026&end=27-06-2026&adults=2",
333
+ rentalIdsIn: favoredRentalIds,
334
+ });
335
+ }
336
+ ```
337
+
338
+ - An empty `rentalIdsIn` array means no restriction: the search returns all results.
339
+ Do not search with an empty favourites list.
340
+ - Values that are not positive whole numbers are dropped. When none are left, the
341
+ search returns no results.
342
+ - `search` and `searchPages` take `rentalIdsIn`; `mapSearch` does not.
343
+
178
344
  ### Invalid Combinations
179
345
 
180
346
  The following flexible-query validation rules apply to v10. Legacy v9 rejects
@@ -203,8 +369,8 @@ Flexible queries require either `nights` or `weekend`, but not both:
203
369
 
204
370
  Flexible date tuples accept `DD-MM-YYYY` and `YYYY-MM-DD`; months use `MM-YYYY`.
205
371
 
206
- Use `rentalIdsIn` to restrict results to specific rental IDs. This option is currently supported by `v10` only.
207
- Use `voucher` to price v10 search results with a voucher code. This option is currently supported by `v10` only.
372
+ Use `rentalIdsIn` to restrict results to specific rental IDs. On v9 it needs an opt-in; see [v9: Favourites As A Search Filter](#v9-favourites-as-a-search-filter).
373
+ Use `voucher` to price results with a voucher code; see [Vouchers](#vouchers).
208
374
  For v10, `pets` is a mapped BooleanFilter exposed by `getFilters` and maps to one pet; use `petsCount` for an exact count and do not send both keys in one query.
209
375
 
210
376
  `limit` defaults to `20`. Treat `cursor` as opaque and pass back `pageInfo.nextCursor` unchanged,
@@ -251,6 +417,46 @@ Use `search` with a large `limit` when the page needs every result before it ren
251
417
  (a sorted list, a map with prices). Use `searchPages` when the first cards should
252
418
  appear before the last page is priced.
253
419
 
420
+ ## Vouchers
421
+
422
+ `voucher` prices the results with a voucher code on v9 and v10. On v9 it changes only
423
+ the prices: it does not narrow the results.
424
+
425
+ ```ts
426
+ await sdk.live.search.search({
427
+ locale: "de-DE",
428
+ query: "start=01-08-2026&end=08-08-2026&adults=2",
429
+ voucher: "SUMMER26",
430
+ });
431
+ ```
432
+
433
+ `mapSearch` takes no voucher.
434
+
435
+ On v9, check a code before pricing with `sdk.live.voucher.validate`. v10 has no such
436
+ operation.
437
+
438
+ ```ts
439
+ const result = await sdk.live.voucher.validate({
440
+ locale: "de-DE",
441
+ code: "SUMMER26",
442
+ start: "01-08-2026",
443
+ end: "04-08-2026",
444
+ });
445
+ // { valid: false, reason: "stay_too_short", label: "Der Aufenthalt ist für diesen Gutscheincode zu kurz." }
446
+ ```
447
+
448
+ - `start` and `end` are optional and take `DD-MM-YYYY` or `YYYY-MM-DD`. Pass them
449
+ to also check the minimum stay and the booking window. `end` must be after `start`.
450
+ - `valid` is `true` only for the reason `valid`. The other reasons are
451
+ `not_yet_valid`, `expired`, `unknown`, `stay_too_short`, `outside_booking_window`
452
+ and `rate_limited`.
453
+ - `label` is a ready sentence in the `locale`. To change it, override the
454
+ translation key `voucher.validate.reason.<reason>`.
455
+ - A blank `code` or a bad date makes the call throw.
456
+ - The Hub limits checks to 10 per minute and 60 per hour. Check when the visitor
457
+ submits the code, not while they type. On `rate_limited`, show the label and do not
458
+ retry right away.
459
+
254
460
  ## Sorting
255
461
 
256
462
  Sorting is optional. The discriminated `sort` union allows exactly one ordering mode per request.
@@ -638,13 +844,21 @@ website-sdk --backend v10 search --locale de-DE --query "adults=2" --limit 10
638
844
  website-sdk --backend v10 search --locale de-DE --query "adults=2" --limit 10 --cursor "10"
639
845
  ```
640
846
 
641
- Restrict results to specific rental IDs or price with a voucher code (`v10` only):
847
+ Restrict results to specific rental IDs or price with a voucher code. On v9, `--rental-ids-in` needs `rentalIdsSearch: true` in the `--config` file or `HUB_RENTAL_IDS_SEARCH=true`:
642
848
 
643
849
  ```sh
644
850
  website-sdk --backend v10 search --locale de-DE --query "adults=2" --rental-ids-in "123,456"
645
- website-sdk --backend v10 search --locale de-DE --query "adults=2" --voucher SUMMER26
851
+ website-sdk --backend v9 search --locale de-DE --query "adults=2" --voucher SUMMER26
852
+ ```
853
+
854
+ Check a voucher code (v9 only):
855
+
856
+ ```sh
857
+ website-sdk --backend v9 voucher validate --code SUMMER26 --start 01-08-2026 --end 08-08-2026
646
858
  ```
647
859
 
860
+ Request and check Hub filters (v9 only): see [v9: Hub Filters](#v9-hub-filters).
861
+
648
862
  Pass sorting as schema-validated JSON:
649
863
 
650
864
  ```sh
@@ -667,5 +881,5 @@ website-sdk --backend v10 search --locale de-DE --query "adults=2" --output pret
667
881
 
668
882
  Environment variables:
669
883
 
670
- - `v9`: `HUB_GRAPHQL_URL`, `HUB_V1_API_BASE_URL`, optional `HUB_V0_API_BASE_URL`, `HUB_API_KEY`, `IMAGE_PROXY_BASE_URL`.
884
+ - `v9`: `HUB_GRAPHQL_URL`, `HUB_V1_API_BASE_URL`, optional `HUB_V0_API_BASE_URL`, optional `HUB_RENTAL_SCOPE_PROPERTY_KIND` (`facility` or `objectGroup`), optional `HUB_RENTAL_IDS_SEARCH` (`true` or `false`), `HUB_API_KEY`, `IMAGE_PROXY_BASE_URL`.
671
885
  - `v10`: `VOFFICE_API_ENDPOINT`, `VOFFICE_SEARCH_ENDPOINT`, `VOFFICE_LOCAL_DEV_ACCESS_TOKEN`, `VOFFICE_IMAGE_BASE_URL`.