@v-office/website-sdk 2.24.0 → 2.25.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 (32) hide show
  1. package/dist/cli.mjs +89 -2
  2. package/dist/{client-DC4LG3CP.mjs → client-0Lgv-Gb_.mjs} +83 -18
  3. package/dist/index.d.mts +17 -5
  4. package/dist/index.mjs +1 -1
  5. package/dist/instructions/CHANGELOG.md +2 -0
  6. package/dist/instructions/MIGRATION.md +2 -0
  7. package/dist/instructions/creation.md +5 -0
  8. package/dist/instructions/rentals.md +75 -0
  9. package/dist/instructions/search.md +1 -2
  10. package/dist/instructions/versions/2.24.1/CHANGELOG.md +17 -0
  11. package/dist/instructions/versions/2.24.1/MIGRATION.md +9 -0
  12. package/dist/instructions/versions/2.25.0/CHANGELOG.md +41 -0
  13. package/dist/instructions/versions/2.25.0/MIGRATION.md +64 -0
  14. package/dist/{to-rental-highlights-C1NF2uuE.mjs → operations-DwURbo0b.mjs} +1 -626
  15. package/dist/{rentals-eqFhtCdT.mjs → rentals-Dn0-kGWD.mjs} +96 -33
  16. package/dist/{search-CKL-8T8q.mjs → search-BLTTQAsG.mjs} +4 -3
  17. package/dist/to-rental-highlights-BL5m3Uen.mjs +626 -0
  18. package/dist/translations/v9/de-DE/core.json +3 -1
  19. package/dist/translations/v9/en-US/core.json +3 -1
  20. package/dist/{v9-data-BnYxa2Ek.mjs → v9-data-C3SWtDGs.mjs} +7 -5
  21. package/instructions/CHANGELOG.md +2 -0
  22. package/instructions/MIGRATION.md +2 -0
  23. package/instructions/creation.md +5 -0
  24. package/instructions/rentals.md +75 -0
  25. package/instructions/search.md +1 -2
  26. package/instructions/versions/2.24.1/CHANGELOG.md +17 -0
  27. package/instructions/versions/2.24.1/MIGRATION.md +9 -0
  28. package/instructions/versions/2.24.1/release.json +3 -0
  29. package/instructions/versions/2.25.0/CHANGELOG.md +41 -0
  30. package/instructions/versions/2.25.0/MIGRATION.md +64 -0
  31. package/instructions/versions/2.25.0/release.json +3 -0
  32. package/package.json +3 -3
@@ -105,6 +105,7 @@ type WebsiteSDKOptions = {
105
105
  translationOverrides?: TranslationOverrides;
106
106
  customAttributes?: CustomAttributeRegistrySnapshot;
107
107
  v9PropertyHighlightSources?: V9PropertyHighlightSourceRegistry;
108
+ v9Reviews?: V9ReviewsOptions;
108
109
  customAttributeFilterDefinitions?: readonly CustomAttributeFilterDefinition[];
109
110
  rentalHighlightPrioritization?: readonly RentalHighlightPrioritizationKey[];
110
111
  rentalPropertyHighlightPrioritization?: readonly RentalPropertyHighlightPrioritizationKey[];
@@ -114,6 +115,10 @@ type WebsiteSDKOptions = {
114
115
  };
115
116
  ```
116
117
 
118
+ `v9Reviews` configures v9 review criteria, whether a v9 review's author shows the
119
+ guest's city, and which incomplete v9 feedbacks become review items. v10 does not use it, but an invalid value fails SDK creation on
120
+ both backends. See "Legacy v9 Reviews" in `rentals.md`.
121
+
117
122
  `searchAllRentalsAtOnce` selects how a site searches, on v9 and v10 alike: every
118
123
  result with prices in one call (portfolios of up to 100 rentals), or paged results
119
124
  plus `mapSearch`. See `search.md`.
@@ -344,6 +344,81 @@ For v10, public answers with the same form-response ID are combined into one rev
344
344
 
345
345
  `createdAt` is the form response's creation timestamp, not a travel date. A text-only rental can have `reviews.items` without `reviews.summary`, so check the summary independently. The localized `summary.count` describes form responses with valid ratings and does not necessarily equal `items.length`.
346
346
 
347
+ ### Legacy v9 Reviews
348
+
349
+ v9 feedbacks carry an overall `avgRating`, a free `text`, and one field per
350
+ review criterion, `fb_<id>`. The criteria are tenant specific: every agency
351
+ defines its own in vOffice, so their IDs, number and labels differ per site, and
352
+ vOffice provides no labels. Configure them per site with `v9Reviews`:
353
+
354
+ ```ts
355
+ const options = {
356
+ v9Reviews: {
357
+ criteria: [
358
+ { v9: "fb_8748", type: "stars", label: { "de-DE": "Sauberkeit", "en-US": "Cleanliness" } },
359
+ { v9: "fb_8749", type: "stars", label: { "de-DE": "Lage", "en-US": "Location" } },
360
+ { v9: "fb_9415", type: "text", label: { "de-DE": "Anmerkung", "en-US": "Note" } },
361
+ ],
362
+ showAuthorCity: false,
363
+ includeItemsWithoutText: false,
364
+ includeItemsWithoutRating: false,
365
+ },
366
+ };
367
+ ```
368
+
369
+ - A `stars` criterion becomes an entry of `reviews.summary.categories`, in the
370
+ configured order, with the `label` of the requested locale and the mean of its
371
+ ratings from 1 to 5 (`0` means not rated and does not count). A criterion that
372
+ no included feedback of a rental rated is left out, so a rental shows only the
373
+ criteria it has.
374
+ - A `text` criterion is appended to the review item's `text`: the feedback text
375
+ first, then each answered text criterion as its label and the answer on the
376
+ next line, separated by blank lines.
377
+ - Without `criteria`, `summary.categories` stays empty.
378
+
379
+ Every criterion needs a non-empty label for `de-DE` and `en-US`, a positive
380
+ `fb_<id>`, and a `type` of `stars` or `text`. Invalid options fail SDK creation
381
+ with every issue listed.
382
+
383
+ Review criteria are optional. Without them the site keeps the overall rating,
384
+ the review count and the review items. When you work on reviews for a v9 site,
385
+ offer the criteria to the site owner as an option. Do not ask for them as a
386
+ required step, and do not block other work on the answer. If the owner wants
387
+ them, ask which criteria to show and what they are called. To find the IDs, run
388
+ the CLI against the site's v9 config:
389
+
390
+ ```sh
391
+ website-sdk --backend v9 review-criteria
392
+ website-sdk --backend v9 review-criteria --rental-ids 212350,212351
393
+ ```
394
+
395
+ It reads the `fb_<id>` fields vOffice returns for the five units with the most
396
+ feedbacks, or for the listed units, and prints each ID with its type and the
397
+ units that have it. vOffice returns averages there only for `stars` criteria, so
398
+ a `text` criterion usually does not appear and its ID must come from the site
399
+ owner. Units vOffice cannot load are listed under `skippedRentalIds`.
400
+
401
+ A v9 review item's `author` is the guest's forename only. The SDK does not
402
+ request the surname. Without a forename the author is `reviews.item.guest`
403
+ ("Gast", "Guest"). With `showAuthorCity: true` the guest's city follows, through
404
+ `reviews.item.authorWithCity` ("Anna aus Hamburg", "Guest from Hamburg"); a
405
+ feedback without a city keeps the name alone. Both keys can be changed with
406
+ `translationOverrides`.
407
+
408
+ By default a v9 feedback becomes a review item only when it has an `avgRating`
409
+ of at least 1 and text. The two switches include feedbacks that miss one of
410
+ these:
411
+
412
+ | Switch | When `true` |
413
+ | --------------------------- | ------------------------------------------------------------------------ |
414
+ | `includeItemsWithoutText` | a rated feedback without text becomes an item with `rating` only |
415
+ | `includeItemsWithoutRating` | a feedback with text but no `avgRating` becomes an item with `text` only |
416
+
417
+ A feedback with neither rating nor text is never an item. `summary.rating` and
418
+ `summary.count` cover the included items with a rating, and `summary.categories`
419
+ covers the included items. When no included item has a rating, `reviews` has
420
+ `items` and no `summary`. A text answer to a `text` criterion counts as text.
421
+
347
422
  ## Configuration
348
423
 
349
424
  `v9` config:
@@ -240,8 +240,7 @@ Backend behavior:
240
240
  - `price`: v9 maps to `price_asc` or `price_desc`. v10 orders priced alternatives by total and direction. v10 price sorting requires a fixed-period or flexible-date query with occupancy; the SDK rejects incomplete requests before transport.
241
241
  - `random`: v9 requests the backend's random ordering. v10 currently keeps the default backend ordering.
242
242
  - `rating`: v9 requests the backend's rating ordering. v10 currently keeps the default backend ordering until rating ordering is implemented.
243
- - v9 may retain backend-promoted results ahead of the requested business order, and its random ordering may be deterministic.
244
- - v10 price ordering follows the backend's boost-first, total-second behavior, so different boost groups are not globally ordered only by price.
243
+ - The SDK does not reorder results: they arrive in the order the backend returns them. v9's random ordering may be the same on every request.
245
244
 
246
245
  v10 additionally supports a stable subset of rental-summary field ordering:
247
246
 
@@ -0,0 +1,17 @@
1
+ # Changelog: 2.24.1
2
+
3
+ The search instructions said that v9 may put "promoted" results first and that v10 sorts by
4
+ price within "boost" groups. Neither is something the SDK does or exposes, and a site cannot
5
+ read or reproduce it. This release corrects the instructions and ships `@v-office/sdk-core`
6
+ 1.24.1.
7
+
8
+ ## Changed
9
+
10
+ - `instructions/search.md` says that the SDK does not reorder search results: they arrive in
11
+ the order the backend returns them. Do not build a page's order on backend boosts or
12
+ promotions.
13
+
14
+ ## Fixed
15
+
16
+ - A v10 search whose alternatives have no `boost` field no longer fails (`@v-office/sdk-core`
17
+ 1.24.1).
@@ -0,0 +1,9 @@
1
+ # Migration: 2.24.0 to 2.24.1
2
+
3
+ ## 1. Upgrade
4
+
5
+ ```sh
6
+ pnpm add @v-office/website-sdk@2.24.1
7
+ ```
8
+
9
+ No changes required. The search API and its output stay the same.
@@ -0,0 +1,3 @@
1
+ {
2
+ "componentsAffectedByHeadlessChange": []
3
+ }
@@ -0,0 +1,41 @@
1
+ # Changelog: 2.25.0
2
+
3
+ A v9 site can show ratings per review criterion on the rental page (cleanliness, location, …),
4
+ and decide which incomplete v9 feedbacks become review items. Every v9 agency defines its own
5
+ criteria, so their IDs and names differ per site: the site configures them. v9 reviews no
6
+ longer show the guest's surname.
7
+
8
+ ## Added
9
+
10
+ - `v9Reviews` option for v9 sites. `criteria` lists the agency's `fb_<id>` criteria in display
11
+ order, each with `type` (`"stars"` or `"text"`) and a label for `de-DE` and `en-US`.
12
+ - A `stars` criterion becomes an entry of `reviews.summary.categories` (`{ label, rating }`):
13
+ the mean of its ratings from 1 to 5 across the rental's included feedbacks. `0` means not
14
+ rated. A criterion no feedback of a rental rated is left out.
15
+ - A `text` criterion is appended to the review item's `text`, as its label and the answer on
16
+ the next line.
17
+ - `showAuthorCity` in `v9Reviews`, `false` by default. When `true`, a v9 review's author reads
18
+ "Anna aus Hamburg" / "Anna from Hamburg" (`reviews.item.authorWithCity`).
19
+ - `includeItemsWithoutText` and `includeItemsWithoutRating` in `v9Reviews`, both `false` by
20
+ default. When `true`, a v9 feedback that has no text or no average rating still becomes a
21
+ review item. `summary.rating` and `summary.count` cover the included items that have a
22
+ rating; when none has one, `reviews` has `items` and no `summary`.
23
+ - `website-sdk --backend v9 review-criteria [--rental-ids <ids>]` lists the `fb_<id>` criteria
24
+ vOffice returns for the five units with the most feedbacks, or for the listed units.
25
+ - Types `V9ReviewsOptions`, `V9ReviewCriterion` and `V9ReviewCriterionDataAttribute`.
26
+
27
+ ## Changed
28
+
29
+ - A v9 review's `author` is the guest's forename only ("Anna, verreist im Mai 2025" instead of
30
+ "Anna Beispiel, verreist im Mai 2025"). The SDK no longer requests the surname. A feedback
31
+ without a forename shows `reviews.item.guest` ("Gast", "Guest"); a missing name no longer
32
+ drops a feedback.
33
+ - v9 rentals request only the review criteria a site configures. Earlier versions requested
34
+ three fixed `fb_*` fields that exist for one vOffice account only, and did not use them.
35
+ - `KnownVofficeFeedbackData` no longer lists `fb_1429`, `fb_4905` and `fb_4906`. They are
36
+ account specific like every other `fb_*` field.
37
+ - Invalid `v9Reviews` options fail SDK creation with every issue listed.
38
+
39
+ Without `v9Reviews`, v9 review output is the same as in 2.24.1 apart from the author. v10 does
40
+ not use the option and keeps the full name, but an invalid value fails SDK creation there too. v10 already returns `summary.categories`
41
+ from its feedback forms.
@@ -0,0 +1,64 @@
1
+ # Migration: 2.24.1 to 2.25.0
2
+
3
+ ## 1. Upgrade
4
+
5
+ ```sh
6
+ pnpm add @v-office/website-sdk@2.25.0
7
+ ```
8
+
9
+ No changes are required. One thing looks different on a v9 site: a review's author is the
10
+ guest's forename only, "Gast" / "Guest" when there is none. The surname is no longer
11
+ available. If the site's own text says "full name" or builds initials from `author`, adjust it.
12
+ To name the guest differently, override `reviews.item.guest` in `translationOverrides`.
13
+
14
+ Everything else in v9 reviews stays as before until the site sets `v9Reviews`.
15
+
16
+ ## 2. Optional: ratings per review criterion on a v9 site
17
+
18
+ This is an offer to the site owner, not a required step. The overall rating, the review count
19
+ and the reviews stay either way.
20
+
21
+ 1. List the agency's criteria:
22
+
23
+ ```sh
24
+ website-sdk --backend v9 review-criteria
25
+ ```
26
+
27
+ Every entry has the `fb_<id>` and whether it is rated with stars. A `text` criterion usually
28
+ does not appear here; its ID has to come from the site owner.
29
+
30
+ 2. Ask the site owner which criteria to show and what they are called, in German and English.
31
+
32
+ 3. Set them in the SDK options:
33
+
34
+ ```ts
35
+ const options = {
36
+ v9Reviews: {
37
+ criteria: [
38
+ { v9: "fb_8748", type: "stars", label: { "de-DE": "Sauberkeit", "en-US": "Cleanliness" } },
39
+ { v9: "fb_8749", type: "stars", label: { "de-DE": "Lage", "en-US": "Location" } },
40
+ ],
41
+ },
42
+ };
43
+ ```
44
+
45
+ 4. Render `reviews.summary.categories` if the site does not yet. Each entry is
46
+ `{ label, rating }`, in the configured order; a rental shows only the criteria it has.
47
+
48
+ ## 3. Optional: the guest's city on a v9 site
49
+
50
+ Set `showAuthorCity: true` in `v9Reviews` to show "Anna aus Hamburg" instead of "Anna". The
51
+ wording comes from `reviews.item.authorWithCity` and can be overridden. A feedback without a
52
+ city keeps the name alone.
53
+
54
+ ## 4. Optional: include incomplete v9 feedbacks
55
+
56
+ By default a v9 feedback needs an average rating and text to become a review item. To show the
57
+ others as well, set `includeItemsWithoutText` or `includeItemsWithoutRating` in `v9Reviews` to
58
+ `true`. Items can then lack `text` or `rating`, as `RentalReview` already allows; render each
59
+ field only when it is present.
60
+
61
+ ## 5. If you used `fb_1429`, `fb_4905` or `fb_4906` as known feedback fields
62
+
63
+ They are no longer part of `KnownVofficeFeedbackData`. Where you pass them as feedback data
64
+ attributes, mark them with `customDataAttribute("fb_1429")` instead.
@@ -0,0 +1,3 @@
1
+ {
2
+ "componentsAffectedByHeadlessChange": []
3
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@v-office/website-sdk",
3
- "version": "2.24.0",
3
+ "version": "2.25.0",
4
4
  "description": "Website-facing SDK facade backed by @v-office/sdk-core",
5
5
  "bin": {
6
6
  "website-sdk": "./dist/cli.mjs"
@@ -42,7 +42,7 @@
42
42
  },
43
43
  "dependencies": {
44
44
  "@graphql-typed-document-node/core": "3.2.0",
45
- "@v-office/sdk-core": "1.24.0",
45
+ "@v-office/sdk-core": "1.24.1",
46
46
  "effect": "4.0.0-rc.115",
47
47
  "graphql": "17.0.2",
48
48
  "yaml": "^2.9.0"
@@ -84,7 +84,7 @@
84
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
85
  "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
86
  "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
- "test:v9:rentals": "node --test src/legacy-v9/static/associate-rentals-with-facilities-by-object-groups.test.ts",
87
+ "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
88
  "test:v9:graphql": "node --test src/legacy-v9/graphql/client.test.ts",
89
89
  "test:v9:availability": "node --test src/legacy-v9/parser/availability/to-initial-availability-calendar-days.test.ts",
90
90
  "test:v9:search": "node --test src/legacy-v9/parser/search/resolve-exact-match.test.ts",