@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.
- package/README.md +8 -0
- package/dist/cli.mjs +406 -12
- package/dist/{client-EtS0Qm3i.mjs → client-CKVwzIQ4.mjs} +381 -53
- package/dist/index.d.mts +45 -6
- 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/availability.md +22 -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 +220 -6
- package/dist/instructions/versions/2.29.0/CHANGELOG.md +62 -0
- package/dist/instructions/versions/2.29.0/MIGRATION.md +97 -0
- package/dist/instructions/versions/2.30.0/CHANGELOG.md +40 -0
- package/dist/instructions/versions/2.30.0/MIGRATION.md +30 -0
- package/dist/{v9-data-C3SWtDGs.mjs → operations-CfjJjdrw.mjs} +3122 -1
- package/dist/{rentals-B4g91vwW.mjs → rentals-cmqp5dTw.mjs} +4 -5
- package/dist/{search-B-lvOmXL.mjs → search-DPsBki_9.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/availability.md +22 -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 +220 -6
- 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/instructions/versions/2.30.0/CHANGELOG.md +40 -0
- package/instructions/versions/2.30.0/MIGRATION.md +30 -0
- package/instructions/versions/2.30.0/release.json +3 -0
- package/package.json +6 -4
- package/dist/operations-DwURbo0b.mjs +0 -2850
|
@@ -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,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.
|
|
207
|
-
Use `voucher` to price
|
|
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
|
|
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
|
|
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`.
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# Changelog: 2.29.0
|
|
2
|
+
|
|
3
|
+
On v9, the search can filter by object group, facility and special offer, a rental scope can
|
|
4
|
+
name an object group, and the SDK gets a favourites list and voucher support. A v9 site with a
|
|
5
|
+
rental scope needs one setup step before its next build; see `MIGRATION.md`.
|
|
6
|
+
|
|
7
|
+
## Added
|
|
8
|
+
|
|
9
|
+
- v9 filters beyond the built-in ones: a `backendFilter` definition works once the be-on! Hub
|
|
10
|
+
has a matching entry for the site's be-on key. The fixed keys are `objectGroup` (vOffice
|
|
11
|
+
object group ID), `facility_search` (vOffice facility ID, not `rental.property.id`), `offers`
|
|
12
|
+
(any special offer) and `offer` (one offer ID). The SDK cannot create a Hub entry, a be-on!
|
|
13
|
+
developer adds it. Without the entry the filter does not filter, and a search with only
|
|
14
|
+
that filter and no period or guests returns no rentals.
|
|
15
|
+
- CLI `website-sdk hub-filters request` writes a Markdown file for a be-on! developer with the
|
|
16
|
+
Hub entries a site needs, and prints the matching `backendFilter` definitions. Flags:
|
|
17
|
+
`--object-group`, `--facility`, `--offers`, `--offer`, `--unit`, `--out`. A rental scope or
|
|
18
|
+
`rentalIdsSearch` adds its key. With environment configuration, the CLI reads the two v9
|
|
19
|
+
settings from the new optional `HUB_RENTAL_SCOPE_PROPERTY_KIND` and `HUB_RENTAL_IDS_SEARCH`.
|
|
20
|
+
- CLI `website-sdk hub-filters check` reports which required Hub entries are missing and exits
|
|
21
|
+
non-zero when one is.
|
|
22
|
+
- v9 config `rentalScopePropertyKind: "facility" | "objectGroup"`, default `"facility"`. With
|
|
23
|
+
`"objectGroup"`, `rentalScope.propertyId` is an object group ID: `getRentals` keeps its
|
|
24
|
+
members and the search filters by it. `rental.property` stays a facility.
|
|
25
|
+
- v9 `sdk.live.rentals.getRentalsByIds({ locale, rentalIds })` loads the rentals with the
|
|
26
|
+
given IDs, for a favourites page. It returns the same items as `getRentals`, in the order
|
|
27
|
+
of `rentalIds`, without duplicates. An ID that is unknown, not numeric or outside the rental
|
|
28
|
+
scope is left out without an error. It needs no Hub entry.
|
|
29
|
+
- v9 config `rentalIdsSearch: true` (default `false`) lets the v9 search take `rentalIdsIn`,
|
|
30
|
+
for favourites that combine with other search filters. It needs a Hub entry. An empty
|
|
31
|
+
`rentalIdsIn` array does not restrict the search.
|
|
32
|
+
- v9 search takes `voucher` and prices the results with that code. It does not narrow the
|
|
33
|
+
results. `mapSearch` takes no voucher.
|
|
34
|
+
- v9 `sdk.live.voucher.validate({ code, start?, end?, locale })` returns
|
|
35
|
+
`{ valid, reason, label }`. `reason` is `valid`, `not_yet_valid`, `expired`, `unknown`,
|
|
36
|
+
`stay_too_short`, `outside_booking_window` or `rate_limited`; `label` is a sentence in the
|
|
37
|
+
`locale`. The Hub allows 10 checks per minute and 60 per hour.
|
|
38
|
+
- CLI commands `rentals-by-ids` and `voucher validate` for v9, and `search --voucher` and
|
|
39
|
+
`search --rental-ids-in` on v9.
|
|
40
|
+
|
|
41
|
+
## Changed
|
|
42
|
+
|
|
43
|
+
- A v9 search now applies the rental scope. Before, a facility scope made a search with a period
|
|
44
|
+
or guests fail, and any other search returned all rentals. The scope works with and without a
|
|
45
|
+
period and combines with other filters.
|
|
46
|
+
- `getRentals` on v9 fails the build when a rental scope is set and the Hub lacks the entry the
|
|
47
|
+
scope needs, or when `rentalIdsSearch` is on and the Hub lacks the `voffice_id` entry. The
|
|
48
|
+
error names the missing key. A previously working facility scope hits this until the Hub
|
|
49
|
+
entry exists. A facility scope next to `facilityObjectGroupRelationAttributeId` also fails
|
|
50
|
+
the build; see `MIGRATION.md`.
|
|
51
|
+
- A v9 search with `rentalIdsIn` throws unless `rentalIdsSearch` is `true`. Before, v9 rejected
|
|
52
|
+
the option in its type.
|
|
53
|
+
- Creating a v9 SDK throws when a `backendFilter` uses the key `voffice_id`, `facility_scope`
|
|
54
|
+
or `objectGroup_scope`. The SDK sets these itself.
|
|
55
|
+
- v9 `rentalScope.propertyId` must be a positive decimal integer up to 2147483647. Values such
|
|
56
|
+
as `"1e2"`, `"0x10"`, `"-5"` or `"0"` used to be read as numbers and now make the SDK throw at
|
|
57
|
+
creation, like any other invalid scope.
|
|
58
|
+
- An `int` `backendFilter` on v9 takes decimal digits up to 2147483647, such as an `offer` ID.
|
|
59
|
+
Values such as `"1e2"`, `"0x10"`, `"2.0"` or `"2147483648"` used to be read as numbers; now
|
|
60
|
+
the search leaves the filter out, as with any other invalid value.
|
|
61
|
+
|
|
62
|
+
v10 is unchanged.
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# Migration: 2.28.1 to 2.29.0
|
|
2
|
+
|
|
3
|
+
## 1. Upgrade
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
pnpm add @v-office/website-sdk@2.29.0
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
v10 sites need no changes. A v9 site without a rental scope needs none either, unless it hits
|
|
10
|
+
step 3. A v9 site with a rental scope must do step 2 before its next build.
|
|
11
|
+
|
|
12
|
+
## 2. v9 with a rental scope: add the Hub entry
|
|
13
|
+
|
|
14
|
+
The search now sends the scope to the be-on! Hub as a filter, so the Hub needs an entry for it:
|
|
15
|
+
`facility_scope` for a facility scope, `objectGroup_scope` for an object group scope. Until the
|
|
16
|
+
entry exists, `getRentals` fails the build and names the missing key. The check protects the
|
|
17
|
+
site: without the entry, the search would not respect the scope.
|
|
18
|
+
|
|
19
|
+
1. Put the `rentalScope` into an options file. If you set `rentalScopePropertyKind`, pass
|
|
20
|
+
it to the CLI too: in a `--config` file, or as `HUB_RENTAL_SCOPE_PROPERTY_KIND` next to the
|
|
21
|
+
other `HUB_*` variables.
|
|
22
|
+
2. Write the request:
|
|
23
|
+
|
|
24
|
+
```sh
|
|
25
|
+
website-sdk --backend v9 --config ./website-sdk-config.json --options ./website-sdk-options.json hub-filters request
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
3. Hand the written `hub-filter-request.md` to a be-on! developer.
|
|
29
|
+
4. After they saved the entries, confirm them. The command exits non-zero while one is missing:
|
|
30
|
+
|
|
31
|
+
```sh
|
|
32
|
+
website-sdk --backend v9 --config ./website-sdk-config.json --options ./website-sdk-options.json hub-filters check
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
A site with a facility scope that also sets `facilityObjectGroupRelationAttributeId` fails the
|
|
36
|
+
build: its listings would use the facilities derived from object groups, its search the facility
|
|
37
|
+
stored on each rental. If the facilities are maintained on the rentals in vOffice, remove
|
|
38
|
+
`facilityObjectGroupRelationAttributeId`. Otherwise set `rentalScopePropertyKind: "objectGroup"`,
|
|
39
|
+
put the object group ID into `rentalScope.propertyId`, and request `objectGroup_scope` instead of
|
|
40
|
+
`facility_scope`.
|
|
41
|
+
|
|
42
|
+
## 3. Check your configuration
|
|
43
|
+
|
|
44
|
+
The SDK now refuses to start in two cases that 2.28.1 accepted:
|
|
45
|
+
|
|
46
|
+
- `rentalScope.propertyId` must be a positive decimal integer up to 2147483647, such as
|
|
47
|
+
`"20748"`. Values like `"1e2"`, `"0x10"`, `"-5"`, `"0"` or `"7.0"` used to be read as numbers;
|
|
48
|
+
write the plain ID instead.
|
|
49
|
+
- A `backendFilter` in `customAttributeFilterDefinitions` cannot use the key `voffice_id`,
|
|
50
|
+
`facility_scope` or `objectGroup_scope`. If the definition is yours, rename it. A renamed
|
|
51
|
+
key needs its own Hub entry to filter anything.
|
|
52
|
+
|
|
53
|
+
## 4. Optional: filters by object group, facility or special offer
|
|
54
|
+
|
|
55
|
+
Ask for the Hub entries, then add the printed definitions to `customAttributeFilterDefinitions`:
|
|
56
|
+
|
|
57
|
+
```sh
|
|
58
|
+
website-sdk --backend v9 --config ./website-sdk-config.json hub-filters request --object-group --offers
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Without a Hub entry a filter does nothing: alone and without a period it returns no rentals,
|
|
62
|
+
with a period it returns every available rental, and next to another filter it is ignored. See
|
|
63
|
+
`search.md`, "v9: Hub Filters", for the keys and their values.
|
|
64
|
+
|
|
65
|
+
## 5. Optional: a favourites page
|
|
66
|
+
|
|
67
|
+
Load the saved rentals directly. No Hub entry is needed:
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
if (sdk.backend === "v9") {
|
|
71
|
+
const rentalIds: string[] = JSON.parse(localStorage.getItem("favoredRentalIDs") ?? "[]");
|
|
72
|
+
const rentals = await sdk.live.rentals.getRentalsByIds({ locale: "de-DE", rentalIds });
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
To also combine favourites with the search filters, set `rentalIdsSearch: true` in the v9 config,
|
|
77
|
+
request the entry with `hub-filters request --unit`, and pass `rentalIdsIn` to the search. Do not
|
|
78
|
+
search with an empty favourites list: an empty `rentalIdsIn` returns all results. The site AI
|
|
79
|
+
should offer this to the user once and ask whether they want it. See `search.md`.
|
|
80
|
+
|
|
81
|
+
## 6. Optional: vouchers
|
|
82
|
+
|
|
83
|
+
`voucher` now prices a v9 search. To tell a visitor whether a code is usable before the quote:
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
if (sdk.backend === "v9") {
|
|
87
|
+
const { valid, label } = await sdk.live.voucher.validate({
|
|
88
|
+
locale: "de-DE",
|
|
89
|
+
code: "SUMMER26",
|
|
90
|
+
start: "01-08-2026",
|
|
91
|
+
end: "08-08-2026",
|
|
92
|
+
});
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Check when the visitor submits the code. The Hub limits checks to 10 per minute and 60 per hour;
|
|
97
|
+
on `rate_limited`, show the label and do not retry right away.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Changelog: 2.30.0
|
|
2
|
+
|
|
3
|
+
On v9, calendar prices now follow the rental's prices by length of stay. Many v9 rentals
|
|
4
|
+
charge less per night for longer stays, for example one price for 1 to 2 nights and a lower
|
|
5
|
+
one from 3 nights. Until now the calendar always showed the highest of these prices, even
|
|
6
|
+
on days where the minimum stay rules the short stays out.
|
|
7
|
+
|
|
8
|
+
## Added
|
|
9
|
+
|
|
10
|
+
- v9 `sdk.live.availability.getStartDateSelectedAvailability` returns `formattedPrice` on
|
|
11
|
+
every day. On a day that can be the end date it is the price of the last night of a stay
|
|
12
|
+
from the selected start date to that day, at the rate for that number of nights. On all
|
|
13
|
+
other days it is `null`.
|
|
14
|
+
- Types `V9StartDateSelectedAvailabilityOutput` and `V9EndDateOption`, the v9 output of
|
|
15
|
+
`getStartDateSelectedAvailability` and one of its days.
|
|
16
|
+
|
|
17
|
+
## Changed
|
|
18
|
+
|
|
19
|
+
- v9 `getInitialAvailability` prices each day at the rate for the minimum stay that applies
|
|
20
|
+
from that day. A rental with a minimum stay of 3 nights shows its 3-night rate instead of
|
|
21
|
+
its 1-night rate.
|
|
22
|
+
|
|
23
|
+
Each night is priced by its own season, as the quote does. When the rental's price list
|
|
24
|
+
cannot be loaded, or has no rate for a day, both calls fall back to the price they returned
|
|
25
|
+
before. v10 availability is unchanged and has no `formattedPrice` on end dates.
|
|
26
|
+
|
|
27
|
+
## Hub filters on v9
|
|
28
|
+
|
|
29
|
+
The user now adds the be-on! Hub filters a site needs. `hub-filters request` no longer
|
|
30
|
+
writes a request to forward to a be-on! developer.
|
|
31
|
+
|
|
32
|
+
- `website-sdk hub-filters request` writes a file with the complete code for the be-on
|
|
33
|
+
key's filter field in the be-on! Hub and the steps to paste it. The code assumes an
|
|
34
|
+
empty field. If the field already holds entries, or the Hub already has one of the
|
|
35
|
+
requested keys, the file tells the user to hand it to a developer.
|
|
36
|
+
- When the Hub already has every requested key, `hub-filters request` writes no file and
|
|
37
|
+
points to `hub-filters check`.
|
|
38
|
+
- The errors for a missing Hub filter in `getRentals`, in a search with `rentalIdsIn` and
|
|
39
|
+
in `hub-filters check` point to `hub-filters request` instead of a be-on! developer. A
|
|
40
|
+
custom `backendFilter` key outside the fixed ones still needs a developer for its entry.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Migration: 2.29.0 to 2.30.0
|
|
2
|
+
|
|
3
|
+
## 1. Upgrade
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
pnpm add @v-office/website-sdk@2.30.0
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
No changes are required. On a v9 site, the per-day prices from `getInitialAvailability` can
|
|
10
|
+
be lower than before, because they now use the rate for the day's minimum stay.
|
|
11
|
+
|
|
12
|
+
A `hub-filter-request.md` from an earlier `hub-filters request` was meant for a be-on!
|
|
13
|
+
developer. Once `hub-filters check` passes, delete it. To add missing Hub filters, run
|
|
14
|
+
`hub-filters request` again and give the user the new file.
|
|
15
|
+
|
|
16
|
+
## 2. Optional: show the price of the stay while the guest picks an end date
|
|
17
|
+
|
|
18
|
+
A date picker that shows a price under each day can switch to the prices of
|
|
19
|
+
`getStartDateSelectedAvailability` once a start date is selected. Only v9 returns them, so
|
|
20
|
+
read them inside a check on the backend:
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
if (sdk.backend === "v9") {
|
|
24
|
+
const { calendarDays } = await sdk.live.availability.getStartDateSelectedAvailability(input);
|
|
25
|
+
// calendarDays[date].formattedPrice: per-night price when the guest leaves on that date,
|
|
26
|
+
// null when the date cannot be the end date
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Render `formattedPrice` as it is.
|