@v-office/website-sdk 2.4.2 → 2.5.0

package/instructions/creation.md

@@ -11,6 +11,7 @@ const sdk = createWebsiteSDK({
   config: {
     backend: "v10",
     apiEndpoint: "https://api.example.com/graphql",
+    searchEndpoint: "https://search.example.com/search",
     accessToken: "...",
     imageBaseUrl: "https://images.example.com",
   },
@@ -58,6 +59,7 @@ const sdk = createWebsiteSDK({
   config: {
     backend: "v10",
     apiEndpoint: "https://api.example.com/graphql",
+    searchEndpoint: "https://search.example.com/search",
     accessToken: "...",
     imageBaseUrl: "https://images.example.com",
   },
@@ -66,6 +68,8 @@ const sdk = createWebsiteSDK({
 
 For v10, `backend: "v10"` is optional in TypeScript, but including it is clearer when config files are shared with the CLI.
 
+For v10, `searchEndpoint` is required as of 2.5.0. It is the full REST search URL including the `/search` path and is a separate host from `apiEndpoint` (which still serves rentals, filters, quote, availability, booking, and contact over GraphQL). Configure it explicitly rather than deriving it from `apiEndpoint`.
+
 ## WebsiteSDKOptions
 
 `options` is optional and is passed separately from backend config:
@@ -88,6 +92,7 @@ const options = defineWebsiteSDKOptions({
 type WebsiteSDKOptions = {
   translationOverrides?: TranslationOverrides;
   customAttributeFilterDefinitions?: readonly CustomAttributeFilterDefinition[];
+  customAttributeDefinitionManifest?: CustomAttributeDefinitionManifest;
   rentalHighlightPrioritization?: readonly RentalHighlightPrioritizationKey[];
   rentalPropertyHighlightPrioritization?: readonly RentalPropertyHighlightPrioritizationKey[];
   rentalScope?: RentalScope;
@@ -98,6 +103,7 @@ type WebsiteSDKOptions = {
 Unset options are normalized by the SDK:
 
 - `customAttributeFilterDefinitions` defaults to `[]`.
+- `customAttributeDefinitionManifest` is omitted unless provided; an absent manifest is treated as empty.
 - `rentalHighlightPrioritization` defaults to the SDK default rental highlight order.
 - `rentalPropertyHighlightPrioritization` defaults to the SDK default property highlight order.
 - `rentalScope` defaults to `{}`.
@@ -176,6 +182,43 @@ Visibility:
 - `internal: true` keeps filters usable by search and compositions but hides them from `getFilters`.
 - `searchable: false` keeps custom attributes as display metadata only.
 
+## Custom Attribute Definition Manifest
+
+The v10 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, use `customAttributeDefinitionManifest` to give the SDK a key-to-ID and ID-to-key mapping:
+
+```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" },
+    },
+  },
+});
+```
+
+```ts
+type CustomAttributeDefinitionManifestEntry = {
+  id: string;
+  key: string;
+  type: "BOOLEAN" | "INT" | "STRING" | "OPTION";
+  visibility: "PUBLIC" | string | null;
+  options?: readonly { value: string; label?: Record<string, string> }[];
+};
+
+type CustomAttributeDefinitionManifest = {
+  byKey: Record<string, CustomAttributeDefinitionManifestEntry>;
+  byId: Record<string, CustomAttributeDefinitionManifestEntry>;
+};
+```
+
+- Generate the manifest at build time from your definitions source, and pass a separate manifest per workspace/environment because IDs are not portable.
+- Custom-attribute keys that have no manifest entry are left in `unusedFilterKeys` instead of being applied as filters.
+- Only definitions with `visibility` of `PUBLIC` (or `null`) are surfaced as v10 search highlights; others are ignored.
+- The manifest is only used by v10 search. v9 and the non-search v10 endpoints ignore it.
+
 ## Translation Overrides
 
 Use `translationOverrides` to override SDK translation keys:
@@ -206,6 +249,7 @@ Example `website-sdk-config.v10.json`:
 {
   "backend": "v10",
   "apiEndpoint": "https://api.example.com/graphql",
+  "searchEndpoint": "https://search.example.com/search",
   "accessToken": "...",
   "imageBaseUrl": "https://images.example.com"
 }

package/instructions/filter.md

@@ -91,6 +91,7 @@ Filter variants:
 {
   "backend": "v10",
   "apiEndpoint": "https://api.example.com/graphql",
+  "searchEndpoint": "https://search.example.com/search",
   "accessToken": "...",
   "imageBaseUrl": "https://images.example.com"
 }
@@ -155,4 +156,4 @@ website-sdk --backend v10 filters --locale de-DE --output pretty
 Environment variables:
 
 - `v9`: `HUB_GRAPHQL_URL`, `HUB_V1_API_BASE_URL`, optional `HUB_V0_API_BASE_URL`, `HUB_API_KEY`, `IMAGE_PROXY_BASE_URL`.
-- `v10`: `VOFFICE_API_ENDPOINT`, `VOFFICE_LOCAL_DEV_ACCESS_TOKEN`, `VOFFICE_IMAGE_BASE_URL`.
+- `v10`: `VOFFICE_API_ENDPOINT`, `VOFFICE_SEARCH_ENDPOINT`, `VOFFICE_LOCAL_DEV_ACCESS_TOKEN`, `VOFFICE_IMAGE_BASE_URL`.

package/instructions/quote.md

@@ -344,4 +344,4 @@ The CLI only creates the initial quote. Additional service, cancellation policy,
 Environment variables:
 
 - `v9`: `HUB_GRAPHQL_URL`, `HUB_V1_API_BASE_URL`, optional `HUB_V0_API_BASE_URL`, `HUB_API_KEY`, `IMAGE_PROXY_BASE_URL`.
-- `v10`: `VOFFICE_API_ENDPOINT`, `VOFFICE_LOCAL_DEV_ACCESS_TOKEN`, `VOFFICE_IMAGE_BASE_URL`.
+- `v10`: `VOFFICE_API_ENDPOINT`, `VOFFICE_SEARCH_ENDPOINT`, `VOFFICE_LOCAL_DEV_ACCESS_TOKEN`, `VOFFICE_IMAGE_BASE_URL`.

package/instructions/rentals.md

@@ -137,6 +137,7 @@ For v10, public answers with the same form-response ID are combined into one rev
 {
   "backend": "v10",
   "apiEndpoint": "https://api.example.com/graphql",
+  "searchEndpoint": "https://search.example.com/search",
   "accessToken": "...",
   "imageBaseUrl": "https://images.example.com"
 }
@@ -179,4 +180,4 @@ website-sdk --backend v10 rentals --locale de-DE --output pretty
 Environment variables:
 
 - `v9`: `HUB_GRAPHQL_URL`, `HUB_V1_API_BASE_URL`, optional `HUB_V0_API_BASE_URL`, `HUB_API_KEY`, `IMAGE_PROXY_BASE_URL`.
-- `v10`: `VOFFICE_API_ENDPOINT`, `VOFFICE_LOCAL_DEV_ACCESS_TOKEN`, `VOFFICE_IMAGE_BASE_URL`.
+- `v10`: `VOFFICE_API_ENDPOINT`, `VOFFICE_SEARCH_ENDPOINT`, `VOFFICE_LOCAL_DEV_ACCESS_TOKEN`, `VOFFICE_IMAGE_BASE_URL`.

package/instructions/search.md

@@ -23,9 +23,38 @@ type RentalSearchInput = {
   voucher?: string;
   limit?: number;
   cursor?: string;
+  sort?: SearchSearchSort;
+};
+
+type SearchSearchSort =
+  | { by: "price"; direction: "ASC" | "DESC" }
+  | { by: "random" }
+  | { by: "rating" }
+  | { by: "field"; orderBy: SearchSearchFieldOrderBy };
+
+type SearchSearchFieldOrderBy = {
+  label?: "ASC" | "DESC";
+  name?: "ASC" | "DESC";
+  roomSummary?: {
+    bathrooms?: "ASC" | "DESC";
+    bedrooms?: "ASC" | "DESC";
+    livingrooms?: "ASC" | "DESC";
+    maxAdults?: "ASC" | "DESC";
+    maxPersons?: "ASC" | "DESC";
+    rooms?: "ASC" | "DESC";
+  };
+  attributes?: {
+    squareMeters?: "ASC" | "DESC";
+  };
+  vicinity?: {
+    beachdistance?: "ASC" | "DESC";
+    citydistance?: "ASC" | "DESC";
+  };
 };
 ```
 
+The v9 facade narrows `sort` to price, random, or rating. The closed field-sorting contract is v10-only. The SDK also exports the corresponding `SearchSearchSortSchema`, variant schemas, types, and `V9SearchSearchSort`.
+
 Sample:
 
 ```json
@@ -34,7 +63,11 @@ Sample:
   "query": "start=01-07-2026&end=08-07-2026&adults=2&children=1&wifi=true",
   "rentalIdsIn": ["123", "456"],
   "voucher": "SUMMER26",
-  "limit": 20
+  "limit": 20,
+  "sort": {
+    "by": "price",
+    "direction": "ASC"
+  }
 }
 ```
 
@@ -130,6 +163,66 @@ For v10, `pets` is a mapped BooleanFilter exposed by `getFilters` and maps to on
 
 `limit` defaults to `20`. Treat `cursor` as opaque and pass back `pageInfo.nextCursor` unchanged.
 
+## Sorting
+
+Sorting is optional. The discriminated `sort` union allows exactly one ordering mode per request.
+
+Price, random, and rating use the same input in v9 and v10:
+
+```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: "random" },
+});
+
+await sdk.live.search.search({
+  locale: "de-DE",
+  query: "adults=2",
+  sort: { by: "rating" },
+});
+```
+
+Backend behavior:
+
+- `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.
+- `random`: v9 requests the backend's random ordering. v10 currently keeps the default backend ordering.
+- `rating`: v9 requests the backend's rating ordering. v10 currently keeps the default backend ordering until rating ordering is implemented.
+- v9 may retain backend-promoted results ahead of the requested business order, and its random ordering may be deterministic.
+- v10 price ordering follows the backend's boost-first, total-second behavior, so different boost groups are not globally ordered only by price.
+
+v10 additionally supports a stable subset of rental-summary field ordering:
+
+```ts
+await sdk.live.search.search({
+  locale: "de-DE",
+  query: "adults=2",
+  sort: {
+    by: "field",
+    orderBy: {
+      label: "ASC",
+      roomSummary: {
+        bedrooms: "DESC",
+      },
+      attributes: {
+        squareMeters: "DESC",
+      },
+      vicinity: {
+        beachdistance: "ASC",
+      },
+    },
+  },
+});
+```
+
+The supported fields are `label`, `name`, all six `roomSummary` counters, `attributes.squareMeters`, `vicinity.beachdistance`, and `vicinity.citydistance`. Unknown fields and nesting are not part of the public type and are rejected before transport by the SDK and CLI. The field variant is excluded from `V9SearchSearchSort` and rejected by the CLI when `--backend v9` is selected.
+
 ## Output
 
 Returns `Promise<RentalSearchOutput>`.
@@ -192,10 +285,22 @@ Sample:
 
 Search items share the rental base fields and may include `scope`, `address`, `property`, `highlights`, and `formattedTotal`. Exact-period results are returned in `items`; alternative-period suggestions are returned in root-level `alternatives`.
 
+## v10 Backend
+
+v10 search runs against the dedicated REST search backend (`POST` to the configured `searchEndpoint`). Existing calls and the output type remain compatible, while the input additionally supports optional sorting. v10 results reflect the REST projection:
+
+- At most five images per item, and no image `category`.
+- `property` is the minimal `{ id, nameOrLabel }` shape. Hydrate `property.location`, `property.images`, or `property.address` from `sdk.static.rentals.getRentals(...)` when a card needs them.
+- Custom-attribute search filters and highlights require a `customAttributeDefinitionManifest`; without it, custom-attribute query keys are left in `unusedFilterKeys` and no custom-attribute highlights are added.
+- Fixed-period and flexible searches are priced by the REST backend and require occupancy.
+- Pagination uses the backend `from`/`size` window behind the same opaque `cursor`, capped at 1,000 results.
+
 ## Configuration
 
 Use flat `WebsiteSDKConfig` files and optional `WebsiteSDKOptions`.
 
+For v10, config requires `searchEndpoint` (the full REST search URL) as of 2.5.0. See `creation.md` for `searchEndpoint` and the `customAttributeDefinitionManifest` option.
+
 Custom filter definitions can extend accepted search query keys. Search requests are rate-limited to one backend request per second with a queue size of five.
 
 ## CLI Usage
@@ -220,6 +325,14 @@ website-sdk --backend v10 search --locale de-DE --query "adults=2" --rental-ids-
 website-sdk --backend v10 search --locale de-DE --query "adults=2" --voucher SUMMER26
 ```
 
+Pass sorting as schema-validated JSON:
+
+```sh
+website-sdk --backend v9 search --locale de-DE --query "adults=2" --sort '{"by":"random"}'
+website-sdk --backend v10 search --locale de-DE --query "start=01-08-2026&end=08-08-2026&adults=2" --sort '{"by":"price","direction":"ASC"}'
+website-sdk --backend v10 search --locale de-DE --query "adults=2" --sort '{"by":"field","orderBy":{"label":"ASC"}}'
+```
+
 Use files instead of environment variables:
 
 ```sh
@@ -235,4 +348,4 @@ website-sdk --backend v10 search --locale de-DE --query "adults=2" --output pret
 Environment variables:
 
 - `v9`: `HUB_GRAPHQL_URL`, `HUB_V1_API_BASE_URL`, optional `HUB_V0_API_BASE_URL`, `HUB_API_KEY`, `IMAGE_PROXY_BASE_URL`.
-- `v10`: `VOFFICE_API_ENDPOINT`, `VOFFICE_LOCAL_DEV_ACCESS_TOKEN`, `VOFFICE_IMAGE_BASE_URL`.
+- `v10`: `VOFFICE_API_ENDPOINT`, `VOFFICE_SEARCH_ENDPOINT`, `VOFFICE_LOCAL_DEV_ACCESS_TOKEN`, `VOFFICE_IMAGE_BASE_URL`.

package/instructions/versions/2.4.2/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog: 2.4.2
+
+Release date: 2026-07-20
+
+This release adds proposed additional-service quantities and combines related v10 public feedback answers into complete review items.
+
+## Added
+
+- Added optional `proposedQuantity` to additional services for both v9 and v10. The field is returned when the backend supplies a line amount, including `0`.
+- Added the `shouldAddProposedAdditionalServiceAmount` website SDK option. When enabled, proposed quantities greater than zero are selected on the initial quote.
+- Added deterministic pagination for v10 public feedback so rental reviews are not limited to the first backend result page.
+
+## Changed
+
+- Renamed the additional-service field `preSelectedQuantity` to `proposedQuantity`.
+- `shouldAddProposedAdditionalServiceAmount` defaults to `false`, so proposed quantities are informational unless consumers opt in to automatic initial selection.
+- Optional services with a backend amount of `0` can still be returned with their unit charge when the backend provides enough pricing data.
+- v10 public feedback answers with the same form-response ID are now combined into one review item instead of being returned as independent rating-only and text-only items.
+- A combined v10 review uses the form-response ID and creation time, averages valid `STARS` answers, and includes its non-empty `TEXT` answers.
+- v10 review summaries now count form responses with a valid rating rather than individual rating answers.
+
+## Migration Impact
+
+- Replace reads of `additionalService.preSelectedQuantity` with `additionalService.proposedQuantity`.
+- Leave `shouldAddProposedAdditionalServiceAmount` unset or `false` to preserve explicit additional-service selection.
+- Set `shouldAddProposedAdditionalServiceAmount: true` only when the initial quote should include positive backend-proposed quantities.
+- Do not assume each v10 review item represents one feedback answer. It now represents one form response and can contain both `rating` and `text`.
+- Treat a v10 review item's `id` and `createdAt` as form-response metadata.
+- Do not use `reviews.items.length` as the review-summary count.
+- No SDK config-shape or service-call changes are required.

package/instructions/versions/2.4.2/MIGRATION.md

@@ -0,0 +1,94 @@
+# Migration: 2.4.1 to 2.4.2
+
+This guide covers upgrading `@v-office/website-sdk` from 2.4.1 to 2.4.2.
+
+2.4.2 keeps `createWebsiteSDK({ config, options })`, the flat `WebsiteSDKConfig`, and the existing quote and rental service calls. The migration affects additional-service quantities and v10 review grouping.
+
+## Additional Services
+
+### Renamed Quantity
+
+The optional `preSelectedQuantity` field is now named `proposedQuantity`:
+
+```ts
+for (const service of quote.additionalServices) {
+  if (service.proposedQuantity !== undefined) {
+    renderProposedQuantity(service.proposedQuantity);
+  }
+}
+```
+
+The value is the backend-proposed quantity, including `0`. It does not indicate that the service is selected in the quote.
+
+Migration: replace every read of `preSelectedQuantity` with `proposedQuantity` and continue to handle the field as optional.
+
+### Initial Selection
+
+Proposed quantities are not selected by default. To add positive proposed quantities to the initial quote, enable the new website SDK option:
+
+```ts
+const sdk = createWebsiteSDK({
+  config,
+  options: defineWebsiteSDKOptions({
+    shouldAddProposedAdditionalServiceAmount: true,
+  }),
+});
+```
+
+When this option is `true`, the SDK adds each service up to its positive `proposedQuantity` while creating the quote. Normal availability and quantity-limit checks still apply. A proposed quantity of `0` is never selected automatically.
+
+Leave the option unset or set it to `false` when users must explicitly select every optional service.
+
+## v10 Rental Reviews
+
+v10 now combines public answers that have the same form-response ID. One review item can therefore contain both its averaged star rating and its text:
+
+```ts
+const review = {
+  id: "form-response-1",
+  author: "Ada Lovelace, visited in July 2026",
+  rating: "5",
+  createdAt: "2026-07-10T10:00:00.000Z",
+  text: "Great stay.",
+};
+```
+
+For each v10 form response:
+
+- `id` is the form-response ID.
+- `createdAt` is the form-response creation time.
+- `rating` is the average of its valid public `STARS` values.
+- `text` contains its non-empty public `TEXT` answers.
+- `author` remains optional when no public customer information is available.
+- The item is omitted when the response has neither a valid rating nor non-empty text.
+
+If a response contains multiple text answers, they are separated by blank lines and non-empty question titles identify the corresponding text. Review items remain sorted by form-response creation time, newest first.
+
+Rendering should continue to check optional fields independently:
+
+```ts
+for (const rental of await sdk.static.rentals.getRentals({ locale: "de-DE" })) {
+  for (const item of rental.reviews?.items ?? []) {
+    if (item.rating !== undefined) renderReviewRating(item.rating);
+    if (item.text !== undefined) renderReviewText(item.text);
+    renderReviewAuthor(item.author ?? "Anonymous");
+  }
+
+  if (rental.reviews?.summary !== undefined) {
+    renderReviewSummary(rental.reviews.summary);
+  }
+}
+```
+
+The localized `reviews.summary.count` now counts form responses that contain a valid rating. It can differ from both the number of raw answers and `reviews.items.length`. Text-only reviews can still produce `reviews.items` without a summary.
+
+The SDK now fetches all v10 public-feedback pages. Consumers do not need to add pagination logic to `getRentals`.
+
+## Recommended Steps
+
+1. Upgrade to `@v-office/website-sdk` 2.4.2.
+2. Rename `preSelectedQuantity` reads to `proposedQuantity`.
+3. Decide whether backend-proposed quantities should be selected automatically.
+4. Expect one v10 review item per usable form response rather than one item per answer.
+5. Keep presence checks for review `rating`, `text`, `author`, and `summary`.
+6. Smoke-test quotes with absent, zero, and positive proposed quantities and rentals with rating-only, text-only, and combined feedback.

package/instructions/versions/2.4.3/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog: 2.4.3
+
+Release date: 2026-07-20
+
+This release adds the instructions that were missing from the 2.4.2 package.
+
+## Added
+
+- Added the missing 2.4.2 changelog and migration instructions for proposed additional-service quantities and grouped v10 reviews.
+
+## Migration Impact
+
+- No runtime behavior or public API changes are introduced relative to 2.4.2.
+- Consumers upgrading from 2.4.1 or earlier should follow `versions/2.4.2/MIGRATION.md`.

package/instructions/versions/2.4.3/MIGRATION.md

@@ -0,0 +1,5 @@
+# Migration: 2.4.2 to 2.4.3
+
+The 2.4.2 package was missing its release instructions. Version 2.4.3 adds those instructions without changing runtime behavior or the public API.
+
+No migration is required from 2.4.2. If upgrading from 2.4.1 or earlier, follow `versions/2.4.2/MIGRATION.md`.

package/instructions/versions/2.5.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog: 2.5.0
+
+Release date: 2026-07-21
+
+This release moves v10 rental search onto the dedicated REST search backend, adds optional cross-backend search sorting, and updates static v10 rental loading. Existing public calls and output types remain compatible.
+
+## Added
+
+- Added the required `searchEndpoint` field to v10 backend config for the REST search endpoint (for example `https://search.example.com/search`).
+- Added the optional `customAttributeDefinitionManifest` SDK option that maps custom-attribute keys to backend definition IDs for v10 search.
+- Added the `VOFFICE_SEARCH_ENDPOINT` environment variable and the `searchEndpoint` config-file field for the CLI.
+- Added optional `SearchSearchInput.sort` support with Effect schemas and exported types for price, random, rating, and a closed v10 rental-summary field-ordering contract.
+- Added the v9-narrowed `V9SearchSearchSort`, which supports price, random, and rating but excludes v10 field ordering.
+- Added schema-validated CLI `search --sort '<JSON>'` support.
+
+## Changed
+
+- v10 `sdk.live.search.search` now calls the REST search backend instead of GraphQL. Period, flexible, occupancy, voucher, filter, and cursor behavior is unchanged.
+- v10 search cards now return at most five images and no image `category`.
+- v10 search-result `property` is now the minimal `{ id, nameOrLabel }` shape; per-property `location`, `images`, and `address` are no longer returned on search cards.
+- v10 custom-attribute search filters and highlights now resolve through `customAttributeDefinitionManifest` instead of a per-search backend lookup.
+- v10 pagination now uses the backend `from`/`size` window directly; the opaque `cursor` and 1,000-result window are unchanged.
+- Price sorting maps to `price_asc`/`price_desc` on v9 and `totalOrderBy` on v10. v10 validates that price sorting has a fixed or flexible pricing mode and occupancy before making a REST request.
+- Supported field sorting maps to v10 `rentalSummaryOrderBy`. The stable subset covers names, room-summary counters, square meters, and beach/city distances. v10 random and rating variants intentionally retain default ordering; v9 forwards them to its backend.
+- v10 `sdk.static.rentals.getRentals` now loads base records from `rentals_listRental` instead of `rentals_listRentalSummary`.
+- v10 rental images are loaded in batches from `rentals_listRentalImage`; only uploaded images are included and existing image output/order is preserved.
+- v10 rental room summaries and room-summary highlights are derived from room types and bed occupancy data, with validation for invalid bed kinds and amounts.
+- v10 rental and rental-image traversal now uses serial keyset pagination instead of offsets. Cursor progress is validated, while the existing public rental and image ordering remains unchanged.
+- The REST search request types retain the `RentalSummary` filter contract independently of static rental GraphQL loading.
+
+## Removed
+
+- Removed the internal per-search GraphQL custom-attribute definition lookup and the temporary v10 search-result cache. Both were internal and have no public API surface.
+- Removed the static-rental dependency on `rentals_listRentalSummary`, including its embedded rental images, room summary, and offset pagination.
+
+## Migration Impact
+
+- v10 config now requires `searchEndpoint`; add it wherever a v10 `WebsiteSDKConfig` is constructed, and set `VOFFICE_SEARCH_ENDPOINT` for environment/CLI usage. See `versions/2.5.0/MIGRATION.md`.
+- To keep custom-attribute search filters and highlights working on v10, provide `customAttributeDefinitionManifest`.
+- v10 consumers that render `property.location`, `property.images`, or `property.address` from search results must hydrate them from `sdk.static.rentals.getRentals(...)` instead.
+- Existing consumers do not need to add sorting because `sort` is optional. See `versions/2.5.0/MIGRATION.md` before adopting backend-specific sorting.
+- Static rental consumers require no code changes, but custom v10 access tokens must permit both `rentals_listRental` and `rentals_listRentalImage`.
+- v9 config and options are unchanged.

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.2",
+  "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.2",
+    "@v-office/sdk-core": "^1.6.0",
     "effect": "4.0.0-beta.85",
     "graphql": "16.14.2",
     "yaml": "^2.9.0"