@v-office/website-sdk 2.4.3 → 2.5.0

package/instructions/versions/2.5.0/MIGRATION.md

@@ -0,0 +1,135 @@
+# Migration: 2.4.3 to 2.5.0
+
+This guide covers upgrading `@v-office/website-sdk` from 2.4.3 to 2.5.0.
+
+2.5.0 keeps `createWebsiteSDK({ config, options })`, the flat `WebsiteSDKConfig`, and existing SDK calls. v10 search now runs against the dedicated REST search backend, which requires one new config field and, for custom-attribute search, one new option. Search input also gains optional sorting, and static v10 rental loading uses the full Rental APIs internally. Existing calls and output types remain compatible.
+
+## Required: v10 searchEndpoint
+
+v10 config now requires `searchEndpoint`, the full REST search URL including the `/search` path:
+
+```ts
+const sdk = createWebsiteSDK({
+  config: {
+    backend: "v10",
+    apiEndpoint: "https://api.example.com/graphql",
+    searchEndpoint: "https://search.example.com/search",
+    accessToken: "...",
+    imageBaseUrl: "https://images.example.com",
+  },
+});
+```
+
+Provide the same value wherever v10 config is built:
+
+- CLI config files add a `searchEndpoint` string field.
+- Environment-based CLI usage reads `VOFFICE_SEARCH_ENDPOINT`.
+
+`apiEndpoint` is still required: v10 rentals, filters, quote, availability, booking, and contact continue to use GraphQL. `searchEndpoint` is a separate host and should be configured explicitly rather than derived from `apiEndpoint`.
+
+## Static Rental Loading (v10)
+
+`sdk.static.rentals.getRentals(...)` keeps the same input, output, rental ordering, image ordering, and localization behavior. Internally, 2.5.0:
+
+- Loads rentals from `rentals_listRental` instead of `rentals_listRentalSummary`.
+- Batch-loads uploaded rental images from `rentals_listRentalImage`.
+- Derives room counts and occupancy summaries from rooms and beds.
+- Uses validated serial keyset pagination for rentals and images instead of offset pagination.
+
+Most consumers require no changes. If your v10 access token uses a custom role or restricted operation allowlist, grant access to both `rentals_listRental` and `rentals_listRentalImage`. A token that can only call `rentals_listRentalSummary` will no longer be sufficient for `getRentals`.
+
+## Custom Attribute Manifest
+
+The REST search backend filters and returns custom attributes by definition ID, while SDK configuration and query strings use keys. Because definition IDs are workspace/environment specific, the SDK no longer looks them up at search time. To use searchable custom-attribute filters or to surface custom-attribute highlights on v10 search results, provide a `customAttributeDefinitionManifest` that maps keys to IDs:
+
+```ts
+const options = defineWebsiteSDKOptions({
+  customAttributeDefinitionManifest: {
+    byKey: {
+      region: { id: "def-1", key: "region", type: "OPTION", visibility: "PUBLIC" },
+    },
+    byId: {
+      "def-1": { id: "def-1", key: "region", type: "OPTION", visibility: "PUBLIC" },
+    },
+  },
+});
+```
+
+Generate the manifest at build time from your definitions source, and pass a separate manifest per workspace/environment because IDs are not portable. Without a manifest:
+
+- Custom-attribute query keys are left in `unusedFilterKeys` rather than applied.
+- Custom-attribute highlights are not added to search items.
+- All other search behavior (period, occupancy, catalog filters, voucher, pagination) is unchanged.
+
+Definitions with `visibility` of `PUBLIC` (or `null`) are surfaced as highlights; others are ignored.
+
+## Optional Search Sorting
+
+`SearchSearchInput` now accepts an optional discriminated sort:
+
+```ts
+type SearchSearchSort =
+  | { by: "price"; direction: "ASC" | "DESC" }
+  | { by: "random" }
+  | { by: "rating" }
+  | { by: "field"; orderBy: SearchSearchFieldOrderBy };
+```
+
+Existing searches require no change. When adopting sorting:
+
+- Price, random, and rating inputs are source-compatible between v9 and v10.
+- v9 price sorting maps to `price_asc`/`price_desc`; random and rating are forwarded to the v9 backend.
+- v10 price sorting maps to `totalOrderBy`. It requires a fixed-period or flexible-date pricing query with occupancy and fails validation before transport when either is missing.
+- v10 random and rating currently select the default backend order.
+- The closed `field` contract maps supported name, room-summary, square-meter, and distance fields to v10 `rentalSummaryOrderBy`; it is excluded from `V9SearchSearchSort`.
+- v9 may retain promoted results before the requested order. v10 price results are ordered by backend boost first and total second.
+
+Examples:
+
+```ts
+await sdk.live.search.search({
+  locale: "de-DE",
+  query: "start=01-08-2026&end=08-08-2026&adults=2",
+  sort: { by: "price", direction: "ASC" },
+});
+
+await sdk.live.search.search({
+  locale: "de-DE",
+  query: "adults=2",
+  sort: { by: "field", orderBy: { label: "ASC" } }, // v10 only
+});
+```
+
+The CLI accepts the same schema as JSON:
+
+```sh
+website-sdk --backend v10 search --locale de-DE --query "start=01-08-2026&end=08-08-2026&adults=2" --sort '{"by":"price","direction":"ASC"}'
+```
+
+See `../../search.md` for all variants, supported field-order examples, backend behavior, and CLI usage.
+
+## Search Result Changes (v10)
+
+The public output type is unchanged, but v10 search cards now reflect the REST projection:
+
+- At most five images per item; search images no longer include `category`.
+- `property` is the minimal `{ id, nameOrLabel }` shape. Hydrate `property.location`, `property.images`, or `property.address` from `sdk.static.rentals.getRentals(...)` when a search card needs them.
+- Exact-period matches are returned in `items` with `formattedTotal`; nearby suggestions are returned in root-level `alternatives`, unchanged.
+
+## Backend Behavior
+
+- Fixed-period and flexible searches are priced by the REST backend; occupancy is required for priced searches.
+- Pagination uses `from`/`size` with the existing opaque `cursor`; a cursor is never advertised beyond the 1,000-result window.
+- Requests remain rate-limited to one backend request per second with a queue size of five.
+- Existing v9 search calls remain compatible; sorting is the only added v9 search capability.
+
+## Recommended Steps
+
+1. Upgrade to `@v-office/website-sdk` 2.5.0.
+2. Add `searchEndpoint` to every v10 `WebsiteSDKConfig` and set `VOFFICE_SEARCH_ENDPOINT` for environment/CLI runs.
+3. If you use custom-attribute search filters or highlights, generate and pass `customAttributeDefinitionManifest`.
+4. Update any search-card UI that reads `property.location`, `property.images`, or `property.address` to hydrate from rentals.
+5. Cap rendered search images at five and stop relying on image `category` for v10 search cards.
+6. If adopting sorting, use only shared variants for code that can run against v9, and keep field ordering in v10-narrowed code.
+7. Confirm the v10 access token permits `rentals_listRental` and `rentals_listRentalImage`, then smoke-test `sdk.static.rentals.getRentals`.
+8. Smoke-test unpriced, fixed-period, and flexible v10 searches, including pagination and any requested ordering.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v-office/website-sdk",
-  "version": "2.4.3",
+  "version": "2.5.0",
   "description": "Website-facing SDK facade backed by @v-office/sdk-core",
   "bin": {
     "website-sdk": "./dist/cli.mjs"
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "@graphql-typed-document-node/core": "3.2.0",
-    "@v-office/sdk-core": "^1.5.3",
+    "@v-office/sdk-core": "^1.6.0",
     "effect": "4.0.0-beta.85",
     "graphql": "16.14.2",
     "yaml": "^2.9.0"