@v-office/website-sdk 2.16.2 → 2.17.0

package/instructions/versions/2.17.0/MIGRATION.md

@@ -0,0 +1,207 @@
+# Migration: 2.16.3 to 2.17.0
+
+2.17.0 adds presentation-ready prices to legacy-v9 initial availability days
+and structured rooms to legacy-v9 rental output. It also represents source bed
+amounts consistently on v9 and v10 by returning one public entry per bed.
+
+Service inputs, configuration, and public TypeScript shapes are unchanged.
+
+## 1. Render Initial Calendar Prices Directly
+
+For v9, `getInitialAvailability` can now return a non-null `formattedPrice` on
+valid start dates:
+
+```ts
+const availability = await sdk.live.availability.getInitialAvailability(input);
+
+for (const [date, day] of Object.entries(availability.calendarDays)) {
+  renderCalendarDay({
+    date,
+    status: day.status,
+    price: day.formattedPrice,
+  });
+}
+```
+
+`formattedPrice` is already localized for the input locale and formatted in the
+unit's configured booking currency. Render it directly. Do not parse it for
+arithmetic and do not replace its currency based on site assumptions.
+
+The field remains `null` when:
+
+- the day cannot be used as a start date
+- the calendar marks the day unavailable
+- the v1 calendar supplies no numeric price
+- the unit currency is missing or cannot be loaded
+
+## 2. Account for the Unit-Currency Request
+
+When no successful unit lookup is cached, a v9 initial-availability call loads
+two resources:
+
+1. the v1 unit calendar
+2. the v1 unit record used to read its booking currency
+
+Successful unit responses are cached by unit ID for the lifetime of the SDK
+instance, including responses without a currency. Failed unit requests are not
+cached and are retried by later initial-availability calls. A failed currency
+request does not fail availability; calendar prices remain `null` instead.
+
+Update HTTP mocks, request-count assertions, and service-worker fixtures that
+previously expected only the calendar request.
+
+No additional config is required. The lookup uses the existing `v1ApiBaseUrl`
+and `apiKey`.
+
+## 3. Read Structured v9 Rooms
+
+When vOffice supplies `roomDetails`, v9 rentals can now contain `rooms`:
+
+```ts
+const rentals = await sdk.static.rentals.getRentals({ locale: "de-DE" });
+
+for (const rental of rentals) {
+  for (const room of rental.rooms ?? []) {
+    renderRoomHeading(room.type);
+    renderRoomAttributes(room.attributes ?? []);
+
+    for (const bed of room.beds ?? []) {
+      renderBed({
+        type: bed.type,
+        kind: bed.kind,
+        attributes: bed.attributes ?? [],
+      });
+    }
+  }
+}
+```
+
+Room types, bed types, bed kinds, and attributes are already localized. Render
+them directly rather than comparing their visible text.
+
+The v9 source supports these per-room Boolean attributes:
+
+- `hasPrivateBathroom`
+- `roomDarkeningOption`
+- `wardrobe`
+
+It supports these per-bed Boolean attributes:
+
+- `childrenOnly`
+- `extraLongBeds`
+- `openFootsection`
+- `raisedBeds`
+
+Translation overrides use the same stable keys as v10:
+
+```text
+Room.type.option.<TYPE>
+RoomAttributes.<attribute>.label
+Bed.type.option.<TYPE>
+Bed.kind.option.<KIND>
+Bed.<attribute>.label
+```
+
+`rooms` remains optional. Keep an absent array valid when vOffice has no
+structured room details or no usable room remains after validation.
+
+## 4. Treat Repeated Beds as Quantity
+
+The public room-bed shape has no `amount` property. From 2.17.0, the SDK expands
+the source amount:
+
+```ts
+// Source
+{ type: "ORDINARY", kind: "SINGLE", amount: 2 }
+
+// Public rooms[].beds
+[
+  { type: "Standard bed", kind: "Single bed" },
+  { type: "Standard bed", kind: "Single bed" },
+]
+```
+
+Each public entry represents one bed. Do not deduplicate entries merely because
+their type, kind, and attributes are identical.
+
+This behavior applies to both backends:
+
+- v9 expands `roomDetails[].beds[].amount`
+- v10 expands `rooms[].beds[].amount`
+
+The v10 change is delivered by `@v-office/sdk-core`. Refresh the lockfile when
+upgrading the website SDK so it resolves the coordinated core version shipped
+for 2.17.0.
+
+Invalid, missing, zero, negative, and fractional v9 amounts do not produce bed
+entries. Other usable rooms and beds remain available.
+
+## 5. Keep Unsupported v9 Room Fields Optional
+
+The v9 source does not provide every v10 room capability. In particular, public
+v9 rooms do not currently expose:
+
+- per-room descriptions
+- source `maxGuests`
+- a structured bed amount; source quantities are represented by repeated entries
+- room IDs or room-image associations
+- `roomSummary`
+
+Do not derive these values from translated room labels or property-description
+prose. Existing top-level `attributes` and `highlights` remain the supported
+display sources for aggregate v9 facts such as bedrooms, bathrooms, rooms, and
+sleeping accommodations.
+
+## 6. Update Snapshots and Complete-Object Assertions
+
+Update expectations that previously assumed:
+
+```ts
+day.formattedPrice === null;
+rental.rooms === undefined;
+room.beds?.length === sourceRoom.beds.length;
+```
+
+New valid behavior includes:
+
+```ts
+day.formattedPrice; // localized string on a priced, valid v9 start date
+rental.rooms; // localized structured v9 rooms when roomDetails exists
+room.beds?.length; // total expanded bed amount, not source record count
+```
+
+Keep both `formattedPrice: null` and missing `rooms` valid because they still
+represent legitimate backend data.
+
+## Required Consumer Work
+
+Applications that use only selected fields and ignore the new output require no
+code changes.
+
+Applications that render or snapshot these areas should:
+
+1. Render `formattedPrice` directly when non-null.
+2. Account for the first v9 initial-availability currency request in mocks.
+3. Render `rental.rooms` as optional structured content.
+4. Treat every `rooms[].beds` entry as one bed and avoid value-based
+   deduplication.
+5. Refresh the lockfile so v10 resolves the coordinated core release.
+6. Update complete-output fixtures and snapshots.
+
+## Recommended Verification
+
+1. Load v9 initial availability for a non-EUR rental and confirm the configured
+   currency is used.
+2. Confirm a missing or failed currency lookup keeps calendar prices `null`
+   without failing availability.
+3. Confirm unavailable, non-start, and price-less dates retain
+   `formattedPrice: null`.
+4. Call initial availability twice for the same rental and confirm a successful
+   unit response is reused; confirm a failed unit request is retried.
+5. Fetch v9 rentals with populated `roomDetails` in both supported locales.
+6. Confirm room and bed labels are localized.
+7. Confirm a source bed amount of two produces two public bed entries on v9 and
+   v10.
+8. Confirm incomplete v9 rooms do not remove other usable rooms or fail the
+   rental.
+9. Confirm rentals without structured source rooms still omit `rooms`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v-office/website-sdk",
-  "version": "2.16.2",
+  "version": "2.17.0",
   "description": "Website-facing SDK facade backed by @v-office/sdk-core",
   "bin": {
     "website-sdk": "./dist/cli.mjs"
@@ -42,7 +42,7 @@
   },
   "dependencies": {
     "@graphql-typed-document-node/core": "3.2.0",
-    "@v-office/sdk-core": "^1.16.1",
+    "@v-office/sdk-core": "^1.18.0",
     "effect": "4.0.0-beta.85",
     "graphql": "17.0.2",
     "yaml": "^2.9.0"
@@ -77,8 +77,9 @@
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check",
     "check": "pnpm run typecheck && pnpm run lint && pnpm run fmt:check",
-    "test": "pnpm run test:v9:properties && pnpm run build && node --test test/*.test.mjs",
-    "test:v9:properties": "node --test codegen/v9/heuristic-generation/generate/property.test.ts src/legacy-v9/parser/rentals/render-property-attribute.test.ts",
+    "test": "pnpm run test:v9:properties && pnpm run test:v9:availability && pnpm run build && node --test test/*.test.mjs",
+    "test:v9:properties": "node --test codegen/v9/heuristic-generation/generate/property.test.ts src/legacy-v9/parser/rentals/render-property-attribute.test.ts src/legacy-v9/parser/rentals/to-rooms.test.ts",
+    "test:v9:availability": "node --test src/legacy-v9/parser/availability/to-initial-availability-calendar-days.test.ts",
     "playground:custom-attributes": "pnpm run build && node --env-file=.env playground/custom-attributes.ts"
   }
 }