@v-office/website-sdk 2.38.0 → 3.1.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 (33) hide show
  1. package/dist/cli.mjs +3 -3
  2. package/dist/{client-CE4V_ybW.mjs → client-C6r06QHZ.mjs} +599 -171
  3. package/dist/index.d.mts +133 -4
  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/booking.md +1 -1
  8. package/dist/instructions/quote.md +33 -19
  9. package/dist/instructions/rentals.md +46 -6
  10. package/dist/instructions/search.md +25 -6
  11. package/dist/instructions/versions/3.0.0/CHANGELOG.md +62 -0
  12. package/dist/instructions/versions/3.0.0/MIGRATION.md +69 -0
  13. package/dist/instructions/versions/3.1.0/CHANGELOG.md +47 -0
  14. package/dist/instructions/versions/3.1.0/MIGRATION.md +32 -0
  15. package/dist/{operations-DMqLD3e2.mjs → operations-Bc3WxjV8.mjs} +79 -3
  16. package/dist/{rentals-BsHvdwQt.mjs → rentals-BP7dfcfg.mjs} +88 -25
  17. package/dist/{search-DqdRIJwF.mjs → search-BvgpkUPo.mjs} +22 -11
  18. package/dist/{to-rental-highlights-BE6TdXYa.mjs → to-rental-highlights-9AbqVIso.mjs} +68 -32
  19. package/dist/translations/v9/de-DE/core.json +7 -1
  20. package/dist/translations/v9/en-US/core.json +7 -1
  21. package/instructions/CHANGELOG.md +2 -0
  22. package/instructions/MIGRATION.md +2 -0
  23. package/instructions/booking.md +1 -1
  24. package/instructions/quote.md +33 -19
  25. package/instructions/rentals.md +46 -6
  26. package/instructions/search.md +25 -6
  27. package/instructions/versions/3.0.0/CHANGELOG.md +62 -0
  28. package/instructions/versions/3.0.0/MIGRATION.md +69 -0
  29. package/instructions/versions/3.0.0/release.json +3 -0
  30. package/instructions/versions/3.1.0/CHANGELOG.md +47 -0
  31. package/instructions/versions/3.1.0/MIGRATION.md +32 -0
  32. package/instructions/versions/3.1.0/release.json +3 -0
  33. package/package.json +5 -4
@@ -1,5 +1,5 @@
1
- import { v as VofficeUnitDataPropertyMetadata } from "./operations-DMqLD3e2.mjs";
2
- import { localeToLanguage, makeTranslate, renderLabeledAttributeValue, renderResolvedCustomAttribute, toCountLabelKey, toCountry, toRentalCapacity } from "@v-office/sdk-core";
1
+ import { v as VofficeUnitDataPropertyMetadata } from "./operations-Bc3WxjV8.mjs";
2
+ import { localeToLanguage, makeTranslate, renderLabeledAttributeValue, renderResolvedCustomAttribute, toCountLabelKey, toCountry, toCustomAttributeFact, toFact, toLocalizedText, toRentalCapacity } from "@v-office/sdk-core";
3
3
  import { Effect } from "effect";
4
4
  //#region src/legacy-v9/parser/rentals/to-localized-string.ts
5
5
  const isNonEmptyString$1 = (value) => typeof value === "string" && value.length > 0;
@@ -259,7 +259,8 @@ const toImage = (imageProxyBaseUrl, entry, locale) => {
259
259
  const imageId = getVofficeDynamicImageId(entry);
260
260
  const src = imageId != null ? buildVofficeDynamicImageUrl(imageId, VOFFICE_DYNAMIC_IMAGE_XL) : path != null ? buildImageUrl(imageProxyBaseUrl, path, IMAGE_DEFAULT_WIDTH) : "";
261
261
  const srcset = imageId != null ? buildVofficeDynamicImageSrcset(imageId, entry.dataImage) : path != null ? buildSrcset(imageProxyBaseUrl, path) : "";
262
- const title = toLocalizedString(entry.dataImage?.titles, locale) ?? entry.image?.title;
262
+ const recordTitle = toLocalizedText(entry.dataImage?.titles, locale);
263
+ const title = recordTitle?.text ?? toLocalizedString(entry.dataImage?.titles, locale) ?? entry.image?.title;
263
264
  const alt = title ?? entry.image?.description ?? "";
264
265
  const metadata = { source: entry.source };
265
266
  if (entry.dataImage != null) metadata.dataImage = entry.dataImage;
@@ -271,6 +272,7 @@ const toImage = (imageProxyBaseUrl, entry, locale) => {
271
272
  metadata
272
273
  };
273
274
  if (title != null) image.title = title;
275
+ if (recordTitle?.fallback !== void 0) image.altFallback = recordTitle.fallback;
274
276
  if (entry.dataImage?.tag != null) image.category = entry.dataImage.tag;
275
277
  return image;
276
278
  };
@@ -279,7 +281,8 @@ const toImages = (imageProxyBaseUrl, rental, locale, data) => {
279
281
  };
280
282
  const toFacilityImages = (images, locale) => images.flatMap((image) => {
281
283
  if (image.id == null) return [];
282
- const title = toLocalizedString(image.titles, locale);
284
+ const recordTitle = toLocalizedText(image.titles, locale);
285
+ const title = recordTitle?.text ?? toLocalizedString(image.titles, locale);
283
286
  const item = {
284
287
  idOrPath: image.id.toString(),
285
288
  src: buildVofficeDynamicImageUrl(image.id, VOFFICE_DYNAMIC_IMAGE_XL),
@@ -293,6 +296,7 @@ const toFacilityImages = (images, locale) => images.flatMap((image) => {
293
296
  item.alt = title;
294
297
  item.title = title;
295
298
  }
299
+ if (recordTitle?.fallback !== void 0) item.altFallback = recordTitle.fallback;
296
300
  if (image.tag != null) item.category = image.tag;
297
301
  return [item];
298
302
  });
@@ -307,33 +311,9 @@ const toLocation = (location) => {
307
311
  };
308
312
  };
309
313
  //#endregion
310
- //#region src/legacy-v9/parser/rentals/render-property-attribute.ts
311
- const renderVofficePropertyAttribute = ({ key, metadata, locale, translate, value }) => Effect.gen(function* () {
312
- if (metadata.sourceType === "OPT") {
313
- if (typeof value !== "number" || !Number.isInteger(value)) return void 0;
314
- const option = metadata.options?.find((candidate) => candidate.value === value);
315
- if (option === void 0) return void 0;
316
- return `${yield* translate(metadata.labelKey, key)}: ${yield* translate(option.labelKey, option.sourceLabel)}`;
317
- }
318
- if (value === false || value === 0 || value === "false" || value === "0" || value == null || value === "") return;
319
- const label = yield* translate(metadata.labelKey, key);
320
- if (metadata.sourceType === "INT" && typeof value === "number") {
321
- if (value === 0) return void 0;
322
- if (key.endsWith("distance")) return `${label}: ${value}m`;
323
- if (key === "squareMeters") return `${value} m²`;
324
- return `${value} ${yield* translate(toCountLabelKey(metadata.labelKey, value), label)}`;
325
- }
326
- return renderLabeledAttributeValue({
327
- key,
328
- label,
329
- locale,
330
- value
331
- });
332
- });
333
- //#endregion
334
314
  //#region codegen/v9/heuristic-generation/rental-highlight-key-map.ts
335
315
  const V9_RENTAL_HIGHLIGHT_KEYS = new Set(Object.keys(VofficeUnitDataPropertyMetadata));
336
- const V9_RENTAL_HIGHLIGHT_KEY_LOOKUP = {
316
+ const V9_RENTAL_HIGHLIGHT_KEY_BY_V10_KEY = {
337
317
  ac: "ac",
338
318
  acCoverage: "acCoverage",
339
319
  accessToPrivateBeach: "privateBeach",
@@ -653,10 +633,57 @@ const V9_RENTAL_HIGHLIGHT_KEY_LOOKUP = {
653
633
  youthgroups: "youthgroups",
654
634
  zoo: "zoo"
655
635
  };
636
+ const V9_RENTAL_HIGHLIGHT_KEY_LOOKUP = V9_RENTAL_HIGHLIGHT_KEY_BY_V10_KEY;
656
637
  const toV9RentalHighlightKey = (key) => {
657
638
  const mappedKey = V9_RENTAL_HIGHLIGHT_KEY_LOOKUP[key] ?? key;
658
639
  return V9_RENTAL_HIGHLIGHT_KEYS.has(mappedKey) ? mappedKey : void 0;
659
640
  };
641
+ const V10_KEYS = new Set(Object.keys(V9_RENTAL_HIGHLIGHT_KEY_BY_V10_KEY));
642
+ /** v9 keys exactly one v10 key maps to. A v9 key several v10 keys share has no single v10 name. */
643
+ const V10_KEY_BY_V9_KEY = (() => {
644
+ const v10KeysByV9Key = /* @__PURE__ */ new Map();
645
+ for (const [v10Key, v9Key] of Object.entries(V9_RENTAL_HIGHLIGHT_KEY_BY_V10_KEY)) v10KeysByV9Key.set(v9Key, [...v10KeysByV9Key.get(v9Key) ?? [], v10Key]);
646
+ return new Map([...v10KeysByV9Key].flatMap(([v9Key, v10Keys]) => v10Keys.length === 1 && v10Keys[0] !== void 0 ? [[v9Key, v10Keys[0]]] : []));
647
+ })();
648
+ /**
649
+ * The key a v9 fact states: the v10 name where v10 has the attribute (`loc_lake` → `locLake`),
650
+ * so a site curates one list for both backends; otherwise the v9 key as the hub names it.
651
+ */
652
+ const toV10FactKey = (v9Key) => V10_KEYS.has(v9Key) ? v9Key : V10_KEY_BY_V9_KEY.get(v9Key) ?? v9Key;
653
+ //#endregion
654
+ //#region src/legacy-v9/parser/rentals/render-property-attribute.ts
655
+ const renderVofficePropertyAttribute = ({ key, metadata, locale, translate, value }) => Effect.gen(function* () {
656
+ if (metadata.sourceType === "OPT") {
657
+ if (typeof value !== "number" || !Number.isInteger(value)) return void 0;
658
+ const option = metadata.options?.find((candidate) => candidate.value === value);
659
+ if (option === void 0) return void 0;
660
+ return `${yield* translate(metadata.labelKey, key)}: ${yield* translate(option.labelKey, option.sourceLabel)}`;
661
+ }
662
+ if (value === false || value === 0 || value === "false" || value === "0" || value == null || value === "") return;
663
+ const label = yield* translate(metadata.labelKey, key);
664
+ if (metadata.sourceType === "INT" && typeof value === "number") {
665
+ if (value === 0) return void 0;
666
+ if (key.endsWith("distance")) return `${label}: ${value}m`;
667
+ if (key === "squareMeters") return `${value} m²`;
668
+ return `${value} ${yield* translate(toCountLabelKey(metadata.labelKey, value), label)}`;
669
+ }
670
+ return renderLabeledAttributeValue({
671
+ key,
672
+ label,
673
+ locale,
674
+ value
675
+ });
676
+ });
677
+ /**
678
+ * The fact of a rendered v9 attribute: its key in v10 naming where v10 has the attribute, and
679
+ * its value as v10 states it — the hub sends a feature as `1`, v10 as `true`. A free text has
680
+ * no value: the hub sends it in the requested language, and `text` carries it.
681
+ */
682
+ const toV9Fact = ({ key, metadata, text, value }) => toFact({
683
+ key: toV10FactKey(key),
684
+ text,
685
+ value: metadata.sourceType === "BOOL" ? true : metadata.sourceType === "TEXT" ? void 0 : value
686
+ });
660
687
  //#endregion
661
688
  //#region src/legacy-v9/parser/rentals/to-rental-highlights.ts
662
689
  const RENTAL_VIEW_HIGHLIGHT_KEYS = /* @__PURE__ */ new Set([
@@ -696,7 +723,11 @@ const toRentalHighlights = ({ locale, translations, highlightPrioritization, cus
696
723
  value
697
724
  });
698
725
  if (highlight != null) {
699
- highlights.push(highlight);
726
+ highlights.push(toCustomAttributeFact({
727
+ attribute,
728
+ text: highlight,
729
+ value
730
+ }));
700
731
  if (isViewHighlight) hasViewHighlight = true;
701
732
  }
702
733
  continue;
@@ -712,11 +743,16 @@ const toRentalHighlights = ({ locale, translations, highlightPrioritization, cus
712
743
  value: knownAttributes[v9Key]
713
744
  });
714
745
  if (highlight != null) {
715
- highlights.push(highlight);
746
+ highlights.push(toV9Fact({
747
+ key: v9Key,
748
+ metadata,
749
+ text: highlight,
750
+ value: knownAttributes[v9Key]
751
+ }));
716
752
  if (isViewHighlight) hasViewHighlight = true;
717
753
  }
718
754
  }
719
755
  return highlights;
720
756
  });
721
757
  //#endregion
722
- export { toFacilityImages as a, toCapacity as c, toLocation as i, toAddress as l, toV9RentalHighlightKey as n, toImages as o, renderVofficePropertyAttribute as r, CAPACITY_DATA_ATTRIBUTES as s, toRentalHighlights as t, toLocalizedString as u };
758
+ export { toLocation as a, CAPACITY_DATA_ATTRIBUTES as c, toLocalizedString as d, toV9RentalHighlightKey as i, toCapacity as l, renderVofficePropertyAttribute as n, toFacilityImages as o, toV9Fact as r, toImages as s, toRentalHighlights as t, toAddress as u };
@@ -9,5 +9,11 @@
9
9
  "voucher.validate.reason.unknown": "Dieser Gutscheincode ist unbekannt.",
10
10
  "voucher.validate.reason.stay_too_short": "Der Aufenthalt ist für diesen Gutscheincode zu kurz.",
11
11
  "voucher.validate.reason.outside_booking_window": "Der gewählte Anreisetag liegt außerhalb des Buchungszeitraums dieses Gutscheincodes.",
12
- "voucher.validate.reason.rate_limited": "Zu viele Versuche. Bitte versuchen Sie es später erneut."
12
+ "voucher.validate.reason.rate_limited": "Zu viele Versuche. Bitte versuchen Sie es später erneut.",
13
+ "insurance.ergo.preContract.documents.PID.label": "Produktinformationsblatt",
14
+ "insurance.ergo.preContract.documents.TCP.label": "Versicherungsbedingungen",
15
+ "insurance.ergo.preContract.documents.PRP.label": "Merkblatt zur Datenverarbeitung",
16
+ "insurance.ergo.preContract.documents.ECI.label": "Kundeninformation elektronischer Geschäftsverkehr",
17
+ "insurance.ergo.preContract.documents.other.label": "Dokument",
18
+ "insurance.ergo.policy.document.label": "Versicherungsschein"
13
19
  }
@@ -9,5 +9,11 @@
9
9
  "voucher.validate.reason.unknown": "This voucher code is unknown.",
10
10
  "voucher.validate.reason.stay_too_short": "The stay is too short for this voucher code.",
11
11
  "voucher.validate.reason.outside_booking_window": "The selected arrival date is outside this voucher code's booking window.",
12
- "voucher.validate.reason.rate_limited": "Too many attempts. Please try again later."
12
+ "voucher.validate.reason.rate_limited": "Too many attempts. Please try again later.",
13
+ "insurance.ergo.preContract.documents.PID.label": "Product information sheet",
14
+ "insurance.ergo.preContract.documents.TCP.label": "Insurance terms",
15
+ "insurance.ergo.preContract.documents.PRP.label": "Data processing notice",
16
+ "insurance.ergo.preContract.documents.ECI.label": "E-commerce customer information",
17
+ "insurance.ergo.preContract.documents.other.label": "Document",
18
+ "insurance.ergo.policy.document.label": "Insurance policy"
13
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/3.1.0/CHANGELOG.md`: release notes for 3.1.0
8
+ - `versions/3.0.0/CHANGELOG.md`: release notes for 3.0.0
7
9
  - `versions/2.38.0/CHANGELOG.md`: release notes for 2.38.0
8
10
  - `versions/2.37.1/CHANGELOG.md`: release notes for 2.37.1
9
11
  - `versions/2.37.0/CHANGELOG.md`: release notes for 2.37.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/3.1.0/MIGRATION.md`: Migration: 3.0.0 to 3.1.0
8
+ - `versions/3.0.0/MIGRATION.md`: Migration: 2.38.0 to 3.0.0
7
9
  - `versions/2.38.0/MIGRATION.md`: Migration: 2.37.1 to 2.38.0
8
10
  - `versions/2.37.1/MIGRATION.md`: Migration: 2.37.0 to 2.37.1
9
11
  - `versions/2.37.0/MIGRATION.md`: Migration: 2.36.2 to 2.37.0
@@ -139,7 +139,7 @@ included in its amount. It contains the formatted deposit and, when nonzero, the
139
139
  amount excluding the deposit. Without a stated deposit there are no `lines`;
140
140
  never derive a deposit from `amount` and a percentage.
141
141
 
142
- An optional `insurancePaymentOptions` array is returned only when post-booking insurance payment is available.
142
+ An optional `insurancePaymentOptions` array is returned only when post-booking insurance payment is available. On v9 with an ERGO plan selected it holds the SEPA debit option, even though the pre-contract does not exist yet: create it with `createInsurancePreContract({ quote, booking })` after `book`, then `selectInsurancePayment` and `bookInsurance`.
143
143
 
144
144
  Sites upgrading from 2.12.0 must replace the former `paymentSchedules` output. See
145
145
  `versions/2.13.0/MIGRATION.md`.
@@ -368,6 +368,23 @@ if (selected.ok) quote = selected.quote;
368
368
 
369
369
  The selected policy is marked with `selected: true`, and the booking card total is recalculated if the policy changes the price. Handle selection errors for unknown or unavailable policy ids.
370
370
 
371
+ On v10 the label of a system policy (Balanced 14 days, Strict 30 days, Very strict 60 days) is
372
+ translated by the SDK. The label of a custom or alternative policy is the agency's own text and
373
+ stays as entered in the PMS, in whatever language that is.
374
+
375
+ ## Texts in the PMS's language
376
+
377
+ The SDK translates its own texts. Texts an agency enters in the PMS come back as entered, and
378
+ the SDK cannot tell their language: the backend states one text, not one per language. On an
379
+ English page they are German unless the agency entered English:
380
+
381
+ - v10: custom and alternative cancellation policy names (`cancellationPolicies[].label`).
382
+ - v9: fee, service and insurance names in the booking card and the additional services, as the
383
+ be-on! Hub sends them for the requested language.
384
+
385
+ To show them in English, enter English names in the PMS. A site that must not show German can
386
+ replace them with its own text by `id`.
387
+
371
388
  ## Insurance
372
389
 
373
390
  Insurance information is exposed on `quote.insurance` when available. The `options` array contains either a `none` option or selectable insurance products.
@@ -422,27 +439,17 @@ quote = await sdk.live.quote.selectInsurance({
422
439
  });
423
440
  ```
424
441
 
425
- For insurance products that require a pre-contract, provide customer information:
442
+ On v9 with ERGO insurance the pre-contract needs the stay booking, so create it after `live.booking.book`. The policy holder is the booking's customer, whose birthdate, mobile number (`contactDetails.phone`) and a covered country (DE, AT, BE, DK, FR, IT, LU, NL, PL, CZ) the booking form has to collect. Every traveler needs a `birthday`, and ERGO is not offered for more than nine travelers:
426
443
 
427
444
  ```ts
428
- quote = await sdk.live.quote.createInsurancePreContract({
429
- quote,
430
- customerInformation: {
431
- destinationCountryCode: "DE",
432
- address: {
433
- street: "Main Street",
434
- housenumber: "1",
435
- postalcode: "12345",
436
- city: "Berlin",
437
- countryCode: "DE",
438
- },
439
- email: "jane@example.com",
440
- mobile: "+49123456789",
441
- },
442
- });
445
+ const booking = await sdk.live.booking.book({ quote, contact, relativeRedirectUrl });
446
+
447
+ quote = await sdk.live.quote.createInsurancePreContract({ quote, booking });
443
448
  ```
444
449
 
445
- Select an insurance payment method before booking insurance:
450
+ Calling it again for the same booking and plan returns the existing pre-contract. Show `quote.insurance.preContract.documents` to the guest before booking the insurance.
451
+
452
+ The booking result lists the SEPA debit option in `insurancePaymentOptions` as soon as an ERGO plan is selected. Select that payment method after the pre-contract and before booking insurance:
446
453
 
447
454
  ```ts
448
455
  quote = await sdk.live.quote.selectInsurancePayment({
@@ -454,7 +461,7 @@ quote = await sdk.live.quote.selectInsurancePayment({
454
461
  });
455
462
  ```
456
463
 
457
- After the rental booking is created, complete insurance booking with the opaque booking result. Keep the live result object; its private backend credentials are intentionally not serialized:
464
+ Complete insurance booking with the opaque booking result. Keep the live result object; its private backend credentials are intentionally not serialized:
458
465
 
459
466
  ```ts
460
467
  const insuranceBooking = await sdk.live.quote.bookInsurance({
@@ -466,7 +473,14 @@ const insuranceBooking = await sdk.live.quote.bookInsurance({
466
473
  This is a breaking change in 2.13.0. The former public `guestToken` input is no
467
474
  longer used; see `versions/2.13.0/MIGRATION.md`.
468
475
 
469
- `v9` supports real insurance option refresh, pre-contract, payment selection, and booking. `v10` currently returns a no-insurance placeholder and insurance actions resolve as not required.
476
+ `v9` supports real insurance option refresh, pre-contract, payment selection, and booking. With ERGO, issued policies can be read and revoked (rejects on other accounts); revoking rejects with ERGO's reason when ERGO refuses:
477
+
478
+ ```ts
479
+ const policy = await sdk.live.insurance.readPolicy({ policyNumber });
480
+ const revoked = await sdk.live.insurance.revokePolicy({ policyNumber, booking });
481
+ ```
482
+
483
+ When the Hub settings or the plan search of ERGO or URV fail, the quote shows insurance as not offered instead of failing. `v10` currently returns a no-insurance placeholder and insurance actions resolve as not required.
470
484
 
471
485
  ## Configuration
472
486
 
@@ -114,14 +114,54 @@ can mark it as German (`lang="de"`, a note):
114
114
  Only fields served in another language are listed; `descriptionFallbacks` is omitted when every
115
115
  text is in the requested locale, and always for `de-DE`.
116
116
 
117
+ Images and rooms say the same with one field each: `altFallback` on an image (its `alt` and
118
+ `title` are in that language) and `descriptionFallback` on a room (v10; v9 rooms have no
119
+ description). Both are omitted when the text is in the requested locale.
120
+
117
121
  - v10 reads every language of a text and takes the German one when the requested one is empty.
118
- - v9: the be-on! Hub already answers a missing translation with the German text, without saying
119
- so. For a locale other than `de-DE`, `getRentals` and `getRentalsByIds` also ask the Hub for
120
- the German texts and mark every field whose text is the same. This is one extra Hub query, of the texts alone, per
121
- 128 rentals (and one facility query with `facilityObjectGroupRelationAttributeId`), only for
122
- non-German locales.
122
+ - v9: per-language image titles are marked as they are read. The be-on! Hub answers every other
123
+ missing translation with the German text, without saying so: for a locale other than `de-DE`,
124
+ `getRentals` and `getRentalsByIds` also ask the Hub for the German descriptions and image
125
+ captions, and mark every one that is the same. This is one extra Hub query, of the texts alone,
126
+ per 128 rentals (and one facility query with `facilityObjectGroupRelationAttributeId`), only
127
+ for non-German locales.
128
+
129
+ Rental names, region names and attribute texts are not covered. Neither are review category
130
+ names: on v10 they are the questions of the agency's feedback form (`summary.categories[].label`),
131
+ one text per question; on v9 they come from the site's `v9Reviews.criteria` labels. See
132
+ `quote.md` for the quote's texts.
133
+
134
+ ### Facts: items with keys
135
+
136
+ Every list of rendered items also states what each item is, the same in every locale:
137
+
138
+ | Items (text) | Facts (key and value) |
139
+ | ------------------------------------ | ------------------------------------------------------------------ |
140
+ | `attributes[].subCategories[].items` | `attributes[].subCategories[].facts` |
141
+ | `vicinity[].items` | `vicinity[].facts` |
142
+ | `highlights` | `highlightFacts` (rentals, their `property`, search items) |
143
+ | `rooms[].attributes` | `rooms[].attributeFacts`; the room type's key is `rooms[].typeKey` |
144
+
145
+ `facts[i]` is `items[i]`: same order, same length.
146
+
147
+ ```ts
148
+ type RentalFact = {
149
+ readonly key: string; // "beachdistance", "wifi", "seaviewType", a custom attribute's key
150
+ readonly text: string; // the item as rendered: "Distance to beach: 300m"
151
+ readonly value?: boolean | number | string; // true, 300, "GOOD"
152
+ };
153
+ ```
154
+
155
+ - `key` is the backend's attribute key. v9 states v10's key where v10 has the attribute
156
+ (`loc_lake` becomes `locLake`), so one curated list works on both backends; a v9 attribute
157
+ several v10 attributes share keeps its v9 key (`beds`, `toiletries`).
158
+ - `value` is the raw value: `true` for a feature (v9 sends `1`, the SDK states `true`), a
159
+ number for a count, a distance in meters or an area in m², an option's key on v10 (`GOOD`),
160
+ its index on v9. A free text has no `value`, `text` carries it: a localized text, a v9 text attribute
161
+ and a custom attribute of type `string` change with the locale.
123
162
 
124
- Rental names, region names and attribute texts are not covered.
163
+ Curate, filter and pick icons by `key`; read distances and counts from `value`. Never match
164
+ `text` or `items`: they change with the locale and with `translationOverrides`.
125
165
 
126
166
  ### Capacity
127
167
 
@@ -621,15 +621,26 @@ Returns `Promise<RentalSearchOutput>`.
621
621
  Priced items and alternative periods share this optional discount shape:
622
622
 
623
623
  ```ts
624
+ type SearchMoney = {
625
+ readonly amount: number; // minor unit of the currency: 103339 = €1,033.39
626
+ readonly currency: string;
627
+ };
628
+
624
629
  type SearchDiscount = {
625
630
  readonly formattedOriginalTotal: string;
631
+ readonly originalTotal?: SearchMoney;
626
632
  readonly applied: readonly {
627
633
  readonly label: string;
628
634
  readonly formattedAmount: string;
635
+ readonly type?: string; // v10 only: EARLY_BIRD, LAST_MINUTE, …
629
636
  }[];
630
637
  };
631
638
  ```
632
639
 
640
+ Next to `formattedTotal`, a priced item or alternative period carries `total` as a
641
+ `SearchMoney`. Compare and calculate with the numbers, never by parsing the formatted
642
+ strings: their separators change with the locale ("1.033,39 €", "€1,033.39").
643
+
633
644
  Sample:
634
645
 
635
646
  ```json
@@ -654,12 +665,15 @@ Sample:
654
665
  ],
655
666
  "highlights": ["2 bedrooms", "WiFi", "Parking"],
656
667
  "formattedTotal": "1.111,00 €",
668
+ "total": { "amount": 111100, "currency": "EUR" },
657
669
  "discount": {
658
670
  "formattedOriginalTotal": "1.234,00 €",
671
+ "originalTotal": { "amount": 123400, "currency": "EUR" },
659
672
  "applied": [
660
673
  {
661
674
  "label": "Frühbucher-Rabatt",
662
- "formattedAmount": "-123,00 €"
675
+ "formattedAmount": "-123,00 €",
676
+ "type": "EARLY_BIRD"
663
677
  }
664
678
  ]
665
679
  }
@@ -710,12 +724,17 @@ Sample:
710
724
  ```
711
725
 
712
726
  Search items share the rental base fields and may include `scope`, `address`,
713
- `capacity` (counts as numbers, see the rentals instructions), `property`, `highlights`,
727
+ `capacity` (counts as numbers, see the rentals instructions), `property`, `highlights`
728
+ with `highlightFacts` (their keys and values, see "Facts" in the rentals instructions),
714
729
  and `formattedTotal`. A priced item or alternative period
715
730
  may also include `discount`. When it does, `formattedTotal` is the final price and
716
731
  `discount.formattedOriginalTotal` is the price before the applied discounts.
717
- Discount totals, labels, and amounts are already localized and formatted for the
718
- requested locale; backend numeric amounts and modifier type keys are not exposed.
732
+ Discount totals, labels, and amounts are localized and formatted for the requested
733
+ locale; `total` and `discount.originalTotal` state the same totals as numbers. On v10,
734
+ each applied discount also states its `type`, which stays the same in every locale while
735
+ its `label` is translated: filter or group campaigns by `type`, not by `label`. v9 states
736
+ no type; its discount `label` is the name entered in the PMS, as the be-on! Hub sends it, in
737
+ the PMS's language (German unless the agency entered English).
719
738
  `applied` may be empty when the backend supplies an original total without
720
739
  individual modifier lines. Exact-period results are returned in `items`;
721
740
  alternative-period suggestions are returned in root-level `alternatives`.
@@ -895,9 +914,9 @@ shape:
895
914
  - Empty basic-filter sets are sent as GraphQL `data: null`, allowing an empty
896
915
  query to browse the scoped searchable inventory without a dummy occupancy
897
916
  value.
898
- - `calc.total` becomes `formattedTotal`.
917
+ - `calc.total` becomes `formattedTotal` and `total` (in EUR).
899
918
  - `discount` is included only when `calc.oTotal` is greater than `calc.total`.
900
- - `calc.oTotal` becomes `discount.formattedOriginalTotal`.
919
+ - `calc.oTotal` becomes `discount.formattedOriginalTotal` and `discount.originalTotal`.
901
920
  - A non-empty `calc.discountName` becomes the label of the single `applied` entry.
902
921
  - The applied amount is the formatted negative difference
903
922
  `calc.total - calc.oTotal`.
@@ -0,0 +1,62 @@
1
+ # Changelog: 3.0.0
2
+
3
+ This release reworks ERGO travel cancellation insurance on v9. The pre-contract is now created
4
+ after the stay booking and takes the policy holder from that booking, travelers are written to the
5
+ vOffice booking, and issued policies can be read and revoked. v10 does not change, and URV
6
+ insurance is booked as before; only the `createInsurancePreContract` call changes on every v9 site.
7
+
8
+ ## Added
9
+
10
+ - `live.insurance.readPolicy({ policyNumber })` returns an ERGO policy: `status` (`active` or
11
+ `revoked`), `revokedAt`, `documentUrl`, `label`, `travelPeriod` and `insuredPersons`.
12
+ - `live.insurance.revokePolicy({ policyNumber, booking })` revokes an ERGO policy. When ERGO
13
+ refuses, the call rejects with ERGO's reason and nothing is removed from the booking. There is
14
+ no revocation deadline in the SDK; ERGO decides.
15
+ - Both methods reject on v9 accounts that do not use ERGO insurance.
16
+ - `V9QuoteCreateInsurancePreContractInput`, `V9InsuranceReadPolicyInput`,
17
+ `V9InsuranceRevokePolicyInput` and `V9InsurancePolicy` are exported.
18
+
19
+ ## Changed
20
+
21
+ - **Breaking (v9):** `live.quote.createInsurancePreContract` takes `{ quote, booking }`, where
22
+ `booking` is the result of `live.booking.book`. The `customerInformation` input is gone. The
23
+ policy holder, address, email and mobile number come from the booking's customer. The destination
24
+ country is always Germany.
25
+ - `createInsurancePreContract` writes the selected travelers to the vOffice booking when the
26
+ booking has no guests yet. A failure there does not stop the insurance.
27
+ - Calling `createInsurancePreContract` again for the same booking and plan returns the existing
28
+ pre-contract with its documents instead of creating a second one. `bookInsurance` returns the
29
+ policy number of an insurance that is already booked instead of booking twice. A stored policy
30
+ only counts when ERGO still reports it as active; a revoked one is ignored, and when ERGO cannot
31
+ be asked the call rejects instead of booking blindly. A booking that already has an active policy for another plan rejects a plan change
32
+ (in `createInsurancePreContract` and `bookInsurance`); revoke that policy first.
33
+ - `createInsurancePreContract` returns all of ERGO's pre-contract documents (product information
34
+ sheet, insurance terms, data processing notice, e-commerce customer information) in
35
+ `preContract.documents`, with labels in the quote's locale. It rejects when ERGO's documents
36
+ cannot be read, because they are the § 7 VVG information the guest has to see.
37
+ - The booked policy document of `bookInsurance` and the SEPA debit option of the quote carry labels
38
+ in the quote's locale (they used to be English).
39
+ - `readPolicy` and `revokePolicy` list the insured travelers of ERGO's answer; a revoke answer
40
+ without travelers returns an empty list.
41
+ - The pre-contract needs the booking customer's birthdate and mobile number, and a customer
42
+ country that ERGO covers (DE, AT, BE, DK, FR, IT, LU, NL, PL, CZ). Otherwise the call rejects with
43
+ a message that names what is missing.
44
+ - `selectInsurance` rejects ERGO selections in which a traveler has no `birthday`.
45
+ - ERGO plans: one card per product, the one without excess preferred; when that leaves a single
46
+ card, the variant with excess is offered as a second card. Cards are ordered without excess
47
+ first, then by premium.
48
+ - More than nine travelers get no ERGO plans, only the no-insurance option.
49
+ - When the Hub settings or the plan search of ERGO or URV fail, the quote reports insurance as not
50
+ offered instead of failing.
51
+ - ERGO refusals now reject with ERGO's own error text.
52
+ - If saving the booked policy in the Hub fails after ERGO accepted the booking,
53
+ `bookInsurance` still returns `booked` with the policy number.
54
+ - Salutations are sent to ERGO as `H` (Herr, Mr., Mr) or `D` (Frau, Mrs., Ms.), and as empty for
55
+ everything else, such as Divers or Keine Angabe. They used to be sent as `F` or as raw text.
56
+
57
+ ## Fixed
58
+
59
+ - A v9 booking with a selected ERGO plan lists the SEPA debit option in
60
+ `insurancePaymentOptions` before the pre-contract exists; it used to omit it.
61
+
62
+ - ERGO policy holders were taken from the first traveler instead of the booking customer.
@@ -0,0 +1,69 @@
1
+ # Migration: 2.38.0 to 3.0.0
2
+
3
+ Every v9 caller of `createInsurancePreContract` has to update the call, because it now takes
4
+ `{ quote, booking }` (see section 2). On accounts that use URV insurance you can drop the call
5
+ instead: it always returns `not_required` there. Only the URV booking behavior stays the same: URV
6
+ is booked inside `live.booking.book`, and `bookInsurance` resolves as not required. v10 does not
7
+ change.
8
+
9
+ ## 1. Upgrade
10
+
11
+ ```sh
12
+ pnpm add @v-office/website-sdk@3.0.0
13
+ ```
14
+
15
+ ## 2. Book the stay first on v9 with ERGO
16
+
17
+ The pre-contract needs the booking, so `live.booking.book` now comes before it. Replace
18
+
19
+ ```ts
20
+ quote = await sdk.live.quote.createInsurancePreContract({ quote, customerInformation });
21
+ const booking = await sdk.live.booking.book({ quote, contact, relativeRedirectUrl });
22
+ ```
23
+
24
+ with
25
+
26
+ ```ts
27
+ const booking = await sdk.live.booking.book({ quote, contact, relativeRedirectUrl });
28
+ quote = await sdk.live.quote.createInsurancePreContract({ quote, booking });
29
+ quote = await sdk.live.quote.selectInsurancePayment({ quote, paymentInformation });
30
+ const insurance = await sdk.live.quote.bookInsurance({ quote, booking });
31
+ ```
32
+
33
+ The booking result already lists the SEPA debit option in `booking.insurancePaymentOptions` when an
34
+ ERGO plan is selected, so offer it from there.
35
+
36
+ Pass the live `booking` object that `book` returned; do not serialize it. Show the pre-contract
37
+ documents (`quote.insurance.preContract.documents`) to the guest before `bookInsurance`.
38
+
39
+ `createInsurancePreContract` no longer asks for `customerInformation`. The booking's customer is
40
+ the policy holder, so the booking form has to collect what ERGO needs:
41
+
42
+ - `contact.birthdate` and a phone number in `contact.contactDetails.phone`, which is sent as the
43
+ mobile number. Without them the call rejects.
44
+ - A country in `contact.address.countryCode` that ERGO covers: DE, AT, BE, DK, FR, IT, LU, NL, PL
45
+ or CZ.
46
+
47
+ Every traveler in `selectInsurance` needs a `birthday`. Offer ERGO only for up to nine travelers;
48
+ with more, the quote contains only the no-insurance option.
49
+
50
+ If the guest returns after a failed attempt, call `createInsurancePreContract` again. It reuses the
51
+ existing pre-contract instead of creating another one.
52
+
53
+ ## 3. Read and revoke policies
54
+
55
+ ```ts
56
+ const policy = await sdk.live.insurance.readPolicy({ policyNumber });
57
+ const revoked = await sdk.live.insurance.revokePolicy({ policyNumber, booking });
58
+ ```
59
+
60
+ `revokePolicy` rejects with ERGO's reason when ERGO refuses, for example after the revocation
61
+ period. Both methods reject on accounts that do not use ERGO insurance, so call them only after
62
+ `bookInsurance` returned `booked`.
63
+
64
+ ## What stays the same
65
+
66
+ - v10: nothing changes.
67
+ - v9 with URV insurance: booking behavior does not change; only the `createInsurancePreContract`
68
+ call has to change or go.
69
+ - `selectInsurance`, `selectInsurancePayment` and `bookInsurance` keep their inputs and outputs.
@@ -0,0 +1,3 @@
1
+ {
2
+ "componentsAffectedByHeadlessChange": ["quote", "booking"]
3
+ }
@@ -0,0 +1,47 @@
1
+ # Changelog: 3.1.0
2
+
3
+ What an English site needed from the SDK to stop reading German words: amenities, distances,
4
+ highlights and room features state their keys and values (facts), search prices come as numbers,
5
+ and v10 discounts state their type. Image alt texts and room descriptions missing in the
6
+ requested language come back in German and are marked, like descriptions since 2.38.0, and the
7
+ SDK translates the v10 system cancellation policies and the be-on! Hub's no-name placeholder.
8
+
9
+ ## Added
10
+
11
+ - `total` on priced search items and alternative periods, and `originalTotal` on their
12
+ `discount`, on v9 and v10: `{ amount, currency }`, with `amount` in the currency's minor unit
13
+ (`103339` = €1,033.39). They state the same totals as `formattedTotal` and
14
+ `discount.formattedOriginalTotal`. v9 states them in EUR, as it formats them.
15
+ - v10: `type` on each `discount.applied` entry (`EARLY_BIRD`, `LAST_MINUTE`, …). It is the same
16
+ in every locale while `label` is translated ("Frühbucher-Rabatt", "Early booking discount").
17
+ v9 states no type: its `label` is the discount name entered in the PMS.
18
+ - The type `SearchMoney`.
19
+ - `altFallback` on images and `descriptionFallback` on rooms: the language their text is in when
20
+ it is not the requested one (`"de-DE"`), omitted otherwise. Mark the text as German
21
+ (`lang="de"`) when it is set.
22
+ - Facts: every rendered list states its items with their keys and values, the same in every
23
+ locale: `facts` next to `items` in attribute subcategories and vicinity groups,
24
+ `highlightFacts` next to `highlights` (rentals, their property, search items), and
25
+ `attributeFacts` and `typeKey` on rooms. A fact is `{ key, text, value? }`: the attribute key,
26
+ the rendered item, and the raw value (`true`, a count, meters, m², an option key). `facts[i]` is
27
+ `items[i]`. The type `RentalFact`.
28
+ v9 states v10's key where v10 has the attribute (`loc_lake` → `locLake`) and features as
29
+ `true`, so a site curates one list for both backends. See "Facts" in `rentals.md`.
30
+
31
+ ## Changed
32
+
33
+ - v10: a system cancellation policy (`SYSTEM_FIRM_14`, `SYSTEM_STRICT_30`, `SYSTEM_STRICT_60`)
34
+ is labelled by the SDK's translation of its type ("Strict (30 days)" on English pages); the
35
+ PMS sent its German name ("Streng (30 Tage)") in every locale. Custom and alternative policies
36
+ keep the agency's label.
37
+ - v9: the be-on! Hub's placeholder for a reviewer without a name ("Gastname nicht genannt") is
38
+ read as no name and becomes `reviews.item.guest` ("Guest" / "Gast").
39
+ - The instructions list the texts that stay in the PMS's language because an agency enters them
40
+ there (`quote.md`, "Texts in the PMS's language").
41
+ - v10: an image (rental, property and search) or a room without a text in the requested locale
42
+ takes its German text and is marked. Before, the text was omitted: English pages had no alt
43
+ text on most images (dev-28: 937 of 951) and no room descriptions.
44
+ - v9: an image title kept per language in the PMS falls back to German and is marked. A caption
45
+ the be-on! Hub sends as plain text is compared with the German one in the same extra query
46
+ `getRentals` already makes for descriptions on non-German pages, which now also reads image
47
+ captions. German pages are unchanged and make no extra query.