@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
@@ -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,3 @@
1
+ {
2
+ "componentsAffectedByHeadlessChange": []
3
+ }
@@ -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.
@@ -0,0 +1,3 @@
1
+ {
2
+ "componentsAffectedByHeadlessChange": ["quote", "booking"]
3
+ }
package/package.json CHANGED
@@ -1,7 +1,8 @@
1
1
  {
2
2
  "name": "@v-office/website-sdk",
3
- "version": "2.28.1",
3
+ "version": "2.30.0",
4
4
  "description": "Website-facing SDK facade backed by @v-office/sdk-core",
5
+ "license": "UNLICENSED",
5
6
  "bin": {
6
7
  "website-sdk": "./dist/cli.mjs"
7
8
  },
@@ -81,13 +82,14 @@
81
82
  "fmt": "oxfmt",
82
83
  "fmt:check": "oxfmt --check",
83
84
  "check": "pnpm run typecheck && pnpm run lint && pnpm run fmt:check",
84
- "test": "pnpm run test:v9:openapi && pnpm run test:v9:properties && pnpm run test:v9:rentals && pnpm run test:v9:graphql && pnpm run test:v9:availability && pnpm run test:v9:search && pnpm run test:v9:booking && pnpm run build && node --test test/*.test.mjs",
85
+ "test": "pnpm run test:cli && pnpm run test:v9:openapi && pnpm run test:v9:properties && pnpm run test:v9:rentals && pnpm run test:v9:graphql && pnpm run test:v9:availability && pnpm run test:v9:search && pnpm run test:v9:booking && pnpm run build && node --test test/*.test.mjs",
86
+ "test:cli": "node --test src/cli/v9-hub-filters.test.ts",
85
87
  "test:v9:openapi": "node --test codegen/v9/php-record.test.ts src/legacy-v9/openapi/setup-response.test.ts src/legacy-v9/openapi/quote-response.test.ts",
86
88
  "test:v9:properties": "node --test codegen/v9/heuristic-generation/generate/property.test.ts src/legacy-v9/property-highlight-sources.test.ts src/legacy-v9/parser/rentals/render-property-attribute.test.ts src/legacy-v9/parser/rentals/to-property.test.ts src/legacy-v9/parser/rentals/to-rooms.test.ts",
87
89
  "test:v9:rentals": "node --test src/legacy-v9/static/associate-rentals-with-facilities-by-object-groups.test.ts src/legacy-v9/parser/rentals/to-reviews.test.ts",
88
90
  "test:v9:graphql": "node --test src/legacy-v9/graphql/client.test.ts",
89
- "test:v9:availability": "node --test src/legacy-v9/parser/availability/to-availability-restrictions-by-date.test.ts src/legacy-v9/parser/availability/to-initial-availability-calendar-days.test.ts src/legacy-v9/parser/availability/to-occupancy-limits.test.ts",
90
- "test:v9:search": "node --test src/legacy-v9/parser/search/resolve-exact-match.test.ts",
91
+ "test:v9:availability": "node --test src/legacy-v9/parser/availability/to-availability-restrictions-by-date.test.ts src/legacy-v9/parser/availability/to-initial-availability-calendar-days.test.ts src/legacy-v9/parser/availability/to-occupancy-limits.test.ts src/legacy-v9/parser/availability/to-rent-night-prices.test.ts src/legacy-v9/parser/availability/to-start-date-selected-calendar-days.test.ts",
92
+ "test:v9:search": "node --test src/legacy-v9/parser/search/resolve-exact-match.test.ts src/legacy-v9/rental-scope.test.ts",
91
93
  "test:v9:booking": "node --test src/legacy-v9/parser/booking/output/to-payment-schedules.test.ts",
92
94
  "playground:custom-attributes": "pnpm run build && node --env-file=.env playground/custom-attributes.ts"
93
95
  }