@v-office/website-sdk 2.4.3 → 2.5.0

package/dist/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/dist/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/dist/{search-Ckz48lwV.mjs → search-D1_b2t11.mjs}

@@ -1,4 +1,4 @@
-import { n as stable_filters_default } from "./client-BORwUo4_.mjs";
+import { n as stable_filters_default } from "./client-Cnf-pbry.mjs";
 import { a as searchQuery, c as VofficeUnitDataFieldSchemas, m as parseVofficeUnitData, n as toImages, r as toAddress, t as toRentalHighlights } from "./to-rental-highlights-CxWlq76f.mjs";
 import { CoreSDKError, STABLE_SEARCH_INPUTS, collectQueryParameters, daysBetweenLocalDates, expandCustomAttributeFilterCompositions, parseChildrenAges, parseOccupancyCount, parseQueryParameters, toCustomAttributeFilterLabel, toFormattedSearchPrice, toIsoDateFromPeriodQueryDate, toQueryString, toStableSearchInputBackendQueryKeys, toStableSearchInputParameterValues, toStableSearchInputQueryKeys, toUnusedFilterKeys } from "@v-office/sdk-core";
 import { Effect } from "effect";
@@ -292,8 +292,18 @@ const toPeriodInput = ({ query }) => Effect.gen(function* () {
 	};
 });
 //#endregion
+//#region src/legacy-v9/parser/search/input/to-voffice-sorting.ts
+const toVofficeSorting = (sort) => {
+	if (sort === void 0) return void 0;
+	switch (sort.by) {
+		case "price": return sort.direction === "ASC" ? "price_asc" : "price_desc";
+		case "random": return "random";
+		case "rating": return "rating";
+	}
+};
+//#endregion
 //#region src/legacy-v9/parser/search/input/to-query-input.ts
-const toQueryInput = ({ query, customAttributeFilterDefinitions, locale, translations }) => Effect.gen(function* () {
+const toQueryInput = ({ query, sort, customAttributeFilterDefinitions, locale, translations }) => Effect.gen(function* () {
 	const compositionResult = expandCustomAttributeFilterCompositions({
 		customAttributeFilterDefinitions,
 		locale,
@@ -325,7 +335,8 @@ const toQueryInput = ({ query, customAttributeFilterDefinitions, locale, transla
 		queryInput: {
 			vofficeData: {
 				filter: Object.keys(filter).length > 0 ? filter : void 0,
-				alternatives: true
+				alternatives: true,
+				sorting: toVofficeSorting(sort)
 			},
 			basicQueryInputs
 		},

package/instructions/CHANGELOG.md

@@ -4,6 +4,7 @@ This file is the versioned changelog index for the website SDK instructions.
 
 ## Versions
 
+- `versions/2.5.0/CHANGELOG.md`: `@v-office/website-sdk` 2.5.0 release notes.
 - `versions/2.4.3/CHANGELOG.md`: `@v-office/website-sdk` 2.4.3 documentation release notes.
 - `versions/2.4.2/CHANGELOG.md`: `@v-office/website-sdk` 2.4.2 release notes.
 - `versions/2.4.0/CHANGELOG.md`: `@v-office/website-sdk` 2.4.0 release notes.

package/instructions/MIGRATION.md

@@ -4,6 +4,7 @@ This file is the versioned migration index for the website SDK instructions.
 
 ## Available Guides
 
+- `versions/2.5.0/MIGRATION.md`: migrate from `@v-office/website-sdk` 2.4.3 to 2.5.0.
 - `versions/2.4.3/MIGRATION.md`: migrate from `@v-office/website-sdk` 2.4.2 to 2.4.3.
 - `versions/2.4.2/MIGRATION.md`: migrate from `@v-office/website-sdk` 2.4.1 to 2.4.2.
 - `versions/2.4.0/MIGRATION.md`: migrate from `@v-office/website-sdk` 2.3.x to 2.4.0.

package/instructions/README.md

@@ -1,6 +1,6 @@
 # Website SDK Instructions
 
-These instructions describe `@v-office/website-sdk` 2.4.3.
+These instructions describe `@v-office/website-sdk` 2.5.0.
 
 Use this directory as the consumer-facing reference for the package:
 
@@ -15,6 +15,7 @@ Use this directory as the consumer-facing reference for the package:
 - `document-structured-json.md`: `sdk.static.documents.getTermsAndPrivacyPolicy` and structured document JSON rendering rules.
 - `CHANGELOG.md`: versioned changelog index.
 - `MIGRATION.md`: versioned migration index.
+- `versions/2.5.0/`: 2.5.0 release notes and 2.4.3-to-2.5.0 migration guide.
 - `versions/2.4.3/`: 2.4.3 documentation release notes and migration guide.
 - `versions/2.4.2/`: 2.4.2 release notes and 2.4.1-to-2.4.2 migration guide.
 - `versions/2.4.0/`: 2.4.0 release notes and 2.3.x-to-2.4.0 migration guide.
@@ -39,6 +40,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",
   },
@@ -63,6 +65,7 @@ try {
 website-sdk --backend v10 rentals --locale de-DE
 website-sdk --backend v9 filters --locale en-US
 website-sdk --backend v10 search --locale de-DE --query "adults=2"
+website-sdk --backend v10 search --locale de-DE --query "adults=2" --sort '{"by":"field","orderBy":{"label":"ASC"}}'
 ```
 
-Config file examples in these docs use the flat `WebsiteSDKConfig` shape introduced in 2.0.0 and kept in 2.4.3.
+Config file examples in these docs use the flat `WebsiteSDKConfig` shape introduced in 2.0.0 and kept in 2.5.0. v10 config additionally requires `searchEndpoint` as of 2.5.0.

package/instructions/availability.md

@@ -118,6 +118,7 @@ Use flat `WebsiteSDKConfig` files.
 {
   "backend": "v10",
   "apiEndpoint": "https://api.example.com/graphql",
+  "searchEndpoint": "https://search.example.com/search",
   "accessToken": "...",
   "imageBaseUrl": "https://images.example.com"
 }
@@ -154,4 +155,4 @@ website-sdk --backend v10 availability initial --rental-id 123 --calculate-from-
 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/booking.md

@@ -162,4 +162,4 @@ website-sdk --backend v10 --config ./website-sdk-config.json booking book --quot
 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/contact.md

@@ -107,4 +107,4 @@ Without `--yes`, the command fails before submitting because contact requests se
 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/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.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.