@v-office/website-sdk 2.28.0 → 2.29.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.
- package/README.md +8 -0
- package/dist/cli.mjs +420 -12
- package/dist/{client-DCXrq6T9.mjs → client-B8cF8Ra1.mjs} +293 -49
- package/dist/index.d.mts +36 -4
- package/dist/index.mjs +1 -1
- package/dist/instructions/CHANGELOG.md +2 -0
- package/dist/instructions/MIGRATION.md +2 -0
- package/dist/instructions/README.md +3 -2
- package/dist/instructions/creation.md +35 -4
- package/dist/instructions/custom-attributes.md +2 -2
- package/dist/instructions/filter.md +5 -3
- package/dist/instructions/quote.md +1 -1
- package/dist/instructions/rentals.md +36 -0
- package/dist/instructions/search.md +214 -6
- package/dist/instructions/versions/2.28.1/CHANGELOG.md +16 -0
- package/dist/instructions/versions/2.28.1/MIGRATION.md +11 -0
- package/dist/instructions/versions/2.29.0/CHANGELOG.md +62 -0
- package/dist/instructions/versions/2.29.0/MIGRATION.md +97 -0
- package/dist/{v9-data-C3SWtDGs.mjs → operations-CfjJjdrw.mjs} +3122 -1
- package/dist/{rentals-BocKluYN.mjs → rentals-DvYUm25t.mjs} +4 -5
- package/dist/{search-BHnJI-nl.mjs → search-BkrzAC9w.mjs} +6 -5
- package/dist/{to-rental-highlights-BL5m3Uen.mjs → to-rental-highlights-D7oepO6s.mjs} +1 -1
- package/dist/translations/v9/de-DE/core.json +8 -1
- package/dist/translations/v9/en-US/core.json +8 -1
- package/instructions/CHANGELOG.md +2 -0
- package/instructions/MIGRATION.md +2 -0
- package/instructions/README.md +3 -2
- package/instructions/creation.md +35 -4
- package/instructions/custom-attributes.md +2 -2
- package/instructions/filter.md +5 -3
- package/instructions/quote.md +1 -1
- package/instructions/rentals.md +36 -0
- package/instructions/search.md +214 -6
- package/instructions/versions/2.28.1/CHANGELOG.md +16 -0
- package/instructions/versions/2.28.1/MIGRATION.md +11 -0
- package/instructions/versions/2.28.1/release.json +3 -0
- package/instructions/versions/2.29.0/CHANGELOG.md +62 -0
- package/instructions/versions/2.29.0/MIGRATION.md +97 -0
- package/instructions/versions/2.29.0/release.json +3 -0
- package/package.json +6 -4
- package/dist/operations-DwURbo0b.mjs +0 -2850
|
@@ -1,7 +1,6 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
3
|
-
import { a as
|
|
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-B8cF8Ra1.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
|
|
2
|
-
import {
|
|
3
|
-
import { n as
|
|
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-B8cF8Ra1.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 {
|
|
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.29.0/CHANGELOG.md`: release notes for 2.29.0
|
|
8
|
+
- `versions/2.28.1/CHANGELOG.md`: release notes for 2.28.1
|
|
7
9
|
- `versions/2.28.0/CHANGELOG.md`: release notes for 2.28.0
|
|
8
10
|
- `versions/2.27.0/CHANGELOG.md`: release notes for 2.27.0
|
|
9
11
|
- `versions/2.26.0/CHANGELOG.md`: release notes for 2.26.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.29.0/MIGRATION.md`: Migration: 2.28.1 to 2.29.0
|
|
8
|
+
- `versions/2.28.1/MIGRATION.md`: Migration: 2.28.0 to 2.28.1
|
|
7
9
|
- `versions/2.28.0/MIGRATION.md`: Migration: 2.27.0 to 2.28.0
|
|
8
10
|
- `versions/2.27.0/MIGRATION.md`: Migration: 2.26.0 to 2.27.0
|
|
9
11
|
- `versions/2.26.0/MIGRATION.md`: Migration: 2.25.0 to 2.26.0
|
package/instructions/README.md
CHANGED
|
@@ -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
|
|
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
|
package/instructions/creation.md
CHANGED
|
@@ -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`
|
|
197
|
-
- `
|
|
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` and hand the file to a be-on!
|
|
216
|
+
developer; 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,
|
|
266
|
-
|
|
290
|
+
For a new v9 `backendFilter` key, a be-on! developer must first add the Hub filter; 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
|
|
394
|
-
|
|
393
|
+
additional v9 keys. SDK configuration does not create those keys in Hub: a be-on! developer
|
|
394
|
+
adds them first; see [v9: Hub Filters](search.md#v9-hub-filters).
|
|
395
395
|
|
|
396
396
|
```ts
|
|
397
397
|
const options = defineWebsiteSDKOptions({
|
package/instructions/filter.md
CHANGED
|
@@ -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,
|
|
124
|
-
|
|
125
|
-
|
|
123
|
+
SDK configuration cannot create a Hub filter: for another v9 key, a be-on! developer
|
|
124
|
+
first adds it to the Hub, 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
|
{
|
package/instructions/quote.md
CHANGED
|
@@ -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
|
|
package/instructions/rentals.md
CHANGED
|
@@ -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
|
package/instructions/search.md
CHANGED
|
@@ -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.
|
|
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,165 @@ 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; a be-on! developer adds it. 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 for a be-on! developer, and prints the matching
|
|
216
|
+
`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, it writes no file.
|
|
229
|
+
|
|
230
|
+
Tell the user to hand the file to a be-on! developer. The file holds the Hub entries
|
|
231
|
+
to add, so do not write them by hand. Once the entries are saved, check them:
|
|
232
|
+
|
|
233
|
+
```sh
|
|
234
|
+
website-sdk --backend v9 --config ./website-sdk-config.json --options ./website-sdk-options.json hub-filters check
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
`hub-filters check` compares every configured `backendFilter` key, the scope key and
|
|
238
|
+
`voffice_id` (when `rentalIdsSearch` is on) with the Hub. It exits non-zero and names
|
|
239
|
+
the missing keys, with the `hub-filters request` flags for the fixed ones. A custom
|
|
240
|
+
key outside the fixed ones has no request flag; a be-on! developer adds its entry by
|
|
241
|
+
hand. It sees only that a key exists, not whether its entry is complete.
|
|
242
|
+
|
|
243
|
+
#### A Filter By Object Group
|
|
244
|
+
|
|
245
|
+
`objectGroup` keeps rentals in one vOffice object group. Use it when the agency sorts
|
|
246
|
+
its rentals into groups in vOffice, for example by location ("Am Strand") or by
|
|
247
|
+
property. It knows nothing but the group membership: a rental in the group always
|
|
248
|
+
matches, whatever the group is called. It does not limit the search to the site's
|
|
249
|
+
rentals; that is the rental scope's job (see `creation.md`).
|
|
250
|
+
|
|
251
|
+
Ask the user which object groups the filter offers. Request `--object-group`, then
|
|
252
|
+
add the printed definition with one option per group. The Hub returns IDs, no
|
|
253
|
+
names: the labels are the group names, and the site keeps them.
|
|
254
|
+
|
|
255
|
+
```ts
|
|
256
|
+
{
|
|
257
|
+
key: "objectGroup",
|
|
258
|
+
source: "backendFilter",
|
|
259
|
+
category: "OTHER",
|
|
260
|
+
label: { "de-DE": "Lage", "en-US": "Location" },
|
|
261
|
+
type: "option",
|
|
262
|
+
options: [
|
|
263
|
+
{ value: "20748", label: { "de-DE": "Am Hafen", "en-US": "At the harbour" } },
|
|
264
|
+
{ value: "20747", label: { "de-DE": "Am Strand", "en-US": "At the beach" } },
|
|
265
|
+
],
|
|
266
|
+
searchable: true,
|
|
267
|
+
internal: false,
|
|
268
|
+
}
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
`getFilters` and `appliedFilters` show the labels. The filter works with and without a
|
|
272
|
+
period or guests and combines with a rental scope as AND. A visitor picks one group at
|
|
273
|
+
a time.
|
|
274
|
+
|
|
275
|
+
#### A Filter By Facility
|
|
276
|
+
|
|
277
|
+
`facility_search` keeps rentals of one facility (Ferienanlage), for a facility select
|
|
278
|
+
in the search. It only finds rentals whose facility is stored on the rental in vOffice.
|
|
279
|
+
A site that sets `facilityObjectGroupRelationAttributeId` links rentals to facilities
|
|
280
|
+
through object groups instead; there the filter matches nothing, so offer the object
|
|
281
|
+
groups with `objectGroup`.
|
|
282
|
+
|
|
283
|
+
Request `--facility`. Its values are vOffice facility IDs, not `rental.property.id`,
|
|
284
|
+
which is a different ID, so do not build filter links from `rental.property.id`. Once
|
|
285
|
+
the Hub entry exists, the CLI prints the definition with the options (ID and name) the
|
|
286
|
+
Hub knows. The English labels are the German names; translate them.
|
|
287
|
+
|
|
288
|
+
#### Special Offers
|
|
289
|
+
|
|
290
|
+
- `offers` keeps rentals with any special offer that vOffice shows to websites. With a
|
|
291
|
+
period, the Hub also asks vOffice whether the offer applies to it. Use it for a
|
|
292
|
+
"special offers only" checkbox or a page listing all deals. Request `--offers`.
|
|
293
|
+
- `offer` keeps rentals linked to one special offer, by vOffice offer ID. Use it for a
|
|
294
|
+
page about one campaign, for example an early-booking deal. It checks neither whether
|
|
295
|
+
the offer is shown to websites nor whether it applies to the requested period, so a
|
|
296
|
+
rental can match after its offer has ended. When the question is "which rentals have
|
|
297
|
+
a deal right now", use `offers`. Request `--offer`.
|
|
298
|
+
|
|
299
|
+
`offers` is a `boolean` definition and `offer` an `int` definition with the offer ID:
|
|
300
|
+
|
|
301
|
+
```ts
|
|
302
|
+
"start=20-06-2026&end=27-06-2026&adults=2&offers";
|
|
303
|
+
"adults=2&offer=4711";
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
v10 does not advertise or execute `backendFilter` definitions.
|
|
307
|
+
|
|
308
|
+
### v9: Favourites As A Search Filter
|
|
309
|
+
|
|
310
|
+
For a favourites page, use `sdk.live.rentals.getRentalsByIds` (see `rentals.md`). It
|
|
311
|
+
needs no Hub entry. Use the search only when favourites must combine with the
|
|
312
|
+
other search filters, for example "favourites available in this period".
|
|
313
|
+
|
|
314
|
+
On v9, `rentalIdsIn` is off by default: a search with `rentalIdsIn` throws, even an
|
|
315
|
+
empty array. Offer it to the user once and ask whether they want favourites as a
|
|
316
|
+
search filter. If yes, set `rentalIdsSearch: true` in the v9 config and request the
|
|
317
|
+
Hub filter with `hub-filters request --unit`. The static `getRentals` then fails the
|
|
318
|
+
build until the Hub filter `voffice_id` exists.
|
|
319
|
+
|
|
320
|
+
```ts
|
|
321
|
+
const favoredRentalIds: string[] = JSON.parse(localStorage.getItem("favoredRentalIDs") ?? "[]");
|
|
322
|
+
|
|
323
|
+
if (favoredRentalIds.length > 0) {
|
|
324
|
+
const result = await sdk.live.search.search({
|
|
325
|
+
locale: "de-DE",
|
|
326
|
+
query: "start=20-06-2026&end=27-06-2026&adults=2",
|
|
327
|
+
rentalIdsIn: favoredRentalIds,
|
|
328
|
+
});
|
|
329
|
+
}
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
- An empty `rentalIdsIn` array means no restriction: the search returns all results.
|
|
333
|
+
Do not search with an empty favourites list.
|
|
334
|
+
- Values that are not positive whole numbers are dropped. When none are left, the
|
|
335
|
+
search returns no results.
|
|
336
|
+
- `search` and `searchPages` take `rentalIdsIn`; `mapSearch` does not.
|
|
337
|
+
|
|
178
338
|
### Invalid Combinations
|
|
179
339
|
|
|
180
340
|
The following flexible-query validation rules apply to v10. Legacy v9 rejects
|
|
@@ -203,8 +363,8 @@ Flexible queries require either `nights` or `weekend`, but not both:
|
|
|
203
363
|
|
|
204
364
|
Flexible date tuples accept `DD-MM-YYYY` and `YYYY-MM-DD`; months use `MM-YYYY`.
|
|
205
365
|
|
|
206
|
-
Use `rentalIdsIn` to restrict results to specific rental IDs.
|
|
207
|
-
Use `voucher` to price
|
|
366
|
+
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).
|
|
367
|
+
Use `voucher` to price results with a voucher code; see [Vouchers](#vouchers).
|
|
208
368
|
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
369
|
|
|
210
370
|
`limit` defaults to `20`. Treat `cursor` as opaque and pass back `pageInfo.nextCursor` unchanged,
|
|
@@ -251,6 +411,46 @@ Use `search` with a large `limit` when the page needs every result before it ren
|
|
|
251
411
|
(a sorted list, a map with prices). Use `searchPages` when the first cards should
|
|
252
412
|
appear before the last page is priced.
|
|
253
413
|
|
|
414
|
+
## Vouchers
|
|
415
|
+
|
|
416
|
+
`voucher` prices the results with a voucher code on v9 and v10. On v9 it changes only
|
|
417
|
+
the prices: it does not narrow the results.
|
|
418
|
+
|
|
419
|
+
```ts
|
|
420
|
+
await sdk.live.search.search({
|
|
421
|
+
locale: "de-DE",
|
|
422
|
+
query: "start=01-08-2026&end=08-08-2026&adults=2",
|
|
423
|
+
voucher: "SUMMER26",
|
|
424
|
+
});
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
`mapSearch` takes no voucher.
|
|
428
|
+
|
|
429
|
+
On v9, check a code before pricing with `sdk.live.voucher.validate`. v10 has no such
|
|
430
|
+
operation.
|
|
431
|
+
|
|
432
|
+
```ts
|
|
433
|
+
const result = await sdk.live.voucher.validate({
|
|
434
|
+
locale: "de-DE",
|
|
435
|
+
code: "SUMMER26",
|
|
436
|
+
start: "01-08-2026",
|
|
437
|
+
end: "04-08-2026",
|
|
438
|
+
});
|
|
439
|
+
// { valid: false, reason: "stay_too_short", label: "Der Aufenthalt ist für diesen Gutscheincode zu kurz." }
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
- `start` and `end` are optional and take `DD-MM-YYYY` or `YYYY-MM-DD`. Pass them
|
|
443
|
+
to also check the minimum stay and the booking window. `end` must be after `start`.
|
|
444
|
+
- `valid` is `true` only for the reason `valid`. The other reasons are
|
|
445
|
+
`not_yet_valid`, `expired`, `unknown`, `stay_too_short`, `outside_booking_window`
|
|
446
|
+
and `rate_limited`.
|
|
447
|
+
- `label` is a ready sentence in the `locale`. To change it, override the
|
|
448
|
+
translation key `voucher.validate.reason.<reason>`.
|
|
449
|
+
- A blank `code` or a bad date makes the call throw.
|
|
450
|
+
- The Hub limits checks to 10 per minute and 60 per hour. Check when the visitor
|
|
451
|
+
submits the code, not while they type. On `rate_limited`, show the label and do not
|
|
452
|
+
retry right away.
|
|
453
|
+
|
|
254
454
|
## Sorting
|
|
255
455
|
|
|
256
456
|
Sorting is optional. The discriminated `sort` union allows exactly one ordering mode per request.
|
|
@@ -638,13 +838,21 @@ website-sdk --backend v10 search --locale de-DE --query "adults=2" --limit 10
|
|
|
638
838
|
website-sdk --backend v10 search --locale de-DE --query "adults=2" --limit 10 --cursor "10"
|
|
639
839
|
```
|
|
640
840
|
|
|
641
|
-
Restrict results to specific rental IDs or price with a voucher code
|
|
841
|
+
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
842
|
|
|
643
843
|
```sh
|
|
644
844
|
website-sdk --backend v10 search --locale de-DE --query "adults=2" --rental-ids-in "123,456"
|
|
645
|
-
website-sdk --backend
|
|
845
|
+
website-sdk --backend v9 search --locale de-DE --query "adults=2" --voucher SUMMER26
|
|
846
|
+
```
|
|
847
|
+
|
|
848
|
+
Check a voucher code (v9 only):
|
|
849
|
+
|
|
850
|
+
```sh
|
|
851
|
+
website-sdk --backend v9 voucher validate --code SUMMER26 --start 01-08-2026 --end 08-08-2026
|
|
646
852
|
```
|
|
647
853
|
|
|
854
|
+
Request and check Hub filters (v9 only): see [v9: Hub Filters](#v9-hub-filters).
|
|
855
|
+
|
|
648
856
|
Pass sorting as schema-validated JSON:
|
|
649
857
|
|
|
650
858
|
```sh
|
|
@@ -667,5 +875,5 @@ website-sdk --backend v10 search --locale de-DE --query "adults=2" --output pret
|
|
|
667
875
|
|
|
668
876
|
Environment variables:
|
|
669
877
|
|
|
670
|
-
- `v9`: `HUB_GRAPHQL_URL`, `HUB_V1_API_BASE_URL`, optional `HUB_V0_API_BASE_URL`, `HUB_API_KEY`, `IMAGE_PROXY_BASE_URL`.
|
|
878
|
+
- `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
879
|
- `v10`: `VOFFICE_API_ENDPOINT`, `VOFFICE_SEARCH_ENDPOINT`, `VOFFICE_LOCAL_DEV_ACCESS_TOKEN`, `VOFFICE_IMAGE_BASE_URL`.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Changelog: 2.28.1
|
|
2
|
+
|
|
3
|
+
On v9, the availability calendar now ends where the rental's prices end. Until now a guest
|
|
4
|
+
could pick dates after the last priced night; the calendar showed no price for them and the
|
|
5
|
+
quote then failed.
|
|
6
|
+
|
|
7
|
+
## Fixed
|
|
8
|
+
|
|
9
|
+
- v9 `sdk.live.availability.getInitialAvailability` no longer offers a check-in whose stay
|
|
10
|
+
runs past the last priced night. Days after the last priced night are unavailable and carry
|
|
11
|
+
no price.
|
|
12
|
+
- v9 `sdk.live.availability.getStartDateSelectedAvailability` offers the day after the last
|
|
13
|
+
priced night as the latest check-out and no day after it.
|
|
14
|
+
|
|
15
|
+
A rental whose prices have no end date keeps its calendar as before. v10 availability is
|
|
16
|
+
unchanged.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Migration: 2.28.0 to 2.28.1
|
|
2
|
+
|
|
3
|
+
## 1. Upgrade
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
pnpm add @v-office/website-sdk@2.28.1
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
No changes are required. On a v9 site, days after the rental's last priced night come back
|
|
10
|
+
as unavailable from both availability calls, so a calendar built on them stops offering
|
|
11
|
+
those dates without any change.
|