@v-office/website-sdk 1.2.1 → 2.1.0

package/instructions/search.md

@@ -0,0 +1,238 @@
+# Search
+
+## Service
+
+Use the live search API to search rentals with a URL query-string style input:
+
+```ts
+const result = await sdk.live.search.search({
+  locale: "de-DE",
+  query: "start=01-07-2026&end=08-07-2026&adults=2&wifi=true",
+});
+```
+
+The service is implemented for both `v9` and `v10` backends and returns normalized rental result items. Filtering by `rentalIdsIn` is currently implemented for `v10` only.
+
+## Input
+
+```ts
+type RentalSearchInput = {
+  locale: "de-DE" | "en-US";
+  query: string;
+  rentalIdsIn?: readonly string[];
+  voucher?: string;
+  limit?: number;
+  cursor?: string;
+};
+```
+
+Sample:
+
+```json
+{
+  "locale": "de-DE",
+  "query": "start=01-07-2026&end=08-07-2026&adults=2&children=1&wifi=true",
+  "rentalIdsIn": ["123", "456"],
+  "voucher": "SUMMER26",
+  "limit": 20
+}
+```
+
+Common stable query keys:
+
+- Period: `start`, `end`, `from`, `till`, `minNights`, `maxNights`; date values support `DD-MM-YYYY` and `YYYY-MM-DD`; `v10` also supports `month`, `dates`, `nights`, and `weekend`.
+- Occupancy: `adults`, `children`, `childrenAges`, `babies`, `pets`, `petsCount`.
+- Filters: use `searchParameterQueryKey` values from `sdk.static.filter.getFilters(...)`.
+
+## Query Structure
+
+The `query` field is a URL query-string style value without a leading `?`.
+
+Use `&` to combine period, occupancy, and filter parameters:
+
+```ts
+"start=20-06-2026&end=27-06-2026&adults=2&wifi";
+```
+
+### Period Queries
+
+Use one supported period structure per query.
+
+Exact period search:
+
+```ts
+"start=20-06-2026&end=27-06-2026";
+```
+
+Flexible search by month:
+
+```ts
+"month=06-2026&nights=7";
+"month=06-2026&month=07-2026&nights=7";
+"month=06-2026&weekend";
+"month=06-2026&month=07-2026&weekend";
+```
+
+Flexible search by exact date tuples:
+
+```ts
+"dates=20-06-2026,22-06-2026&nights=2";
+"dates=20-06-2026,22-06-2026&dates=04-07-2026,11-07-2026&nights=2";
+"dates=20-06-2026,22-06-2026&weekend";
+"dates=20-06-2026,22-06-2026&dates=04-07-2026,11-07-2026&weekend";
+```
+
+### Occupancy And Filters
+
+Append occupancy and filter parameters with `&`:
+
+```ts
+"start=20-06-2026&end=27-06-2026&adults=2";
+"start=20-06-2026&end=27-06-2026&adults=2&childrenAges=5%2C13&babies=1&pets=1";
+"start=20-06-2026&end=27-06-2026&adults=2&wifi";
+```
+
+Boolean filters can be provided as presence-only flags when supported:
+
+```ts
+"wifi";
+"wifi&bbq=true";
+```
+
+### Invalid Combinations
+
+Do not mix exact period search with flexible period options:
+
+```ts
+"start=20-06-2026&end=27-06-2026&nights=7";
+"start=20-06-2026&end=27-06-2026&weekend";
+```
+
+Do not mix `month` and `dates` in the same flexible query:
+
+```ts
+"month=06-2026&dates=20-06-2026,22-06-2026&nights=2";
+```
+
+Flexible queries require either `nights` or `weekend`, but not both:
+
+```ts
+"month=06-2026";
+"dates=20-06-2026,22-06-2026";
+"month=06-2026&nights=7&weekend";
+```
+
+Dates should use `DD-MM-YYYY`; months should use `MM-YYYY`.
+
+Use `rentalIdsIn` to restrict results to specific rental IDs. This option is currently supported by `v10` only.
+Use `voucher` to price v10 search results with a voucher code. This option is currently supported by `v10` only.
+For v10, `pets` is a mapped BooleanFilter exposed by `getFilters` and maps to one pet; use `petsCount` for an exact count and do not send both keys in one query.
+
+`limit` defaults to `20`. Treat `cursor` as opaque and pass back `pageInfo.nextCursor` unchanged.
+
+## Output
+
+Returns `Promise<RentalSearchOutput>`.
+
+Sample:
+
+```json
+{
+  "items": [
+    {
+      "id": "123",
+      "nameOrLabel": "Apartment Meerblick",
+      "timeZone": "Europe/Berlin",
+      "rentalType": "Apartment",
+      "location": {
+        "latitude": 54.123,
+        "longitude": 8.456
+      },
+      "images": [
+        {
+          "idOrPath": "image-1",
+          "src": "https://images.example.com/image-1.jpg",
+          "srcset": "https://images.example.com/image-1.jpg 1x",
+          "alt": "Apartment Meerblick"
+        }
+      ],
+      "highlights": ["2 bedrooms", "WiFi", "Parking"],
+      "formattedTotal": "1.234,00 €"
+    }
+  ],
+  "alternatives": [
+    {
+      "item": {
+        "id": "456",
+        "nameOrLabel": "Apartment Düne",
+        "timeZone": "Europe/Berlin"
+      },
+      "alternativePeriods": [
+        {
+          "start": "2026-07-10",
+          "end": "2026-07-17",
+          "formattedTotal": "1.456,00 €"
+        }
+      ]
+    }
+  ],
+  "appliedFilters": [
+    {
+      "key": "wifi",
+      "label": "WiFi"
+    }
+  ],
+  "unusedFilterKeys": [],
+  "pageInfo": {
+    "hasNextPage": true,
+    "nextCursor": "20"
+  }
+}
+```
+
+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`.
+
+## Configuration
+
+Use flat `WebsiteSDKConfig` files and optional `WebsiteSDKOptions`.
+
+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
+
+Run a search with environment-based config:
+
+```sh
+website-sdk --backend v10 search --locale de-DE --query "start=01-07-2026&end=08-07-2026&adults=2"
+```
+
+Paginate with `--limit` and `--cursor`:
+
+```sh
+website-sdk --backend v10 search --locale de-DE --query "adults=2" --limit 10
+website-sdk --backend v10 search --locale de-DE --query "adults=2" --limit 10 --cursor "10"
+```
+
+Restrict results to specific rental IDs or price with a voucher code (`v10` only):
+
+```sh
+website-sdk --backend v10 search --locale de-DE --query "adults=2" --rental-ids-in "123,456"
+website-sdk --backend v10 search --locale de-DE --query "adults=2" --voucher SUMMER26
+```
+
+Use files instead of environment variables:
+
+```sh
+website-sdk --backend v10 --config ./website-sdk-config.json --options ./website-sdk-options.json search --locale de-DE --query "adults=2"
+```
+
+Output defaults to JSON. Use `--output pretty` for inspected terminal output:
+
+```sh
+website-sdk --backend v10 search --locale de-DE --query "adults=2" --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`.

package/instructions/versions/2.0.0/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog: 2.0.0
+
+Release date: 2026-06-24
+
+This release moves the website SDK to the `@v-office/website-sdk` 2.0.0 facade backed by `@v-office/sdk-core`.
+
+## From
+
+- Legacy CMS-style website SDK API.
+- Main construction API: `createCMSSDKFromParsedConfig(config)`.
+- Nested backend config shape: `{ backend, v9: {...}, options }` or `{ backend, v10: {...}, options }`.
+
+## To
+
+- `@v-office/website-sdk` 2.0.0.
+- Main construction API: `createWebsiteSDK({ config, options })`.
+- Flat backend config shape: `WebsiteSDKConfig`.
+- Separate options shape: `WebsiteSDKOptions`.
+
+## Breaking Changes
+
+- Replaced `createCMSSDKFromParsedConfig(config)` with `createWebsiteSDK({ config, options })`.
+- Changed SDK config from nested `ParsedCMSConfig` objects to flat `WebsiteSDKConfig` objects.
+- Moved SDK options out of config objects and into the separate `options` argument.
+- Renamed the primary public SDK type from `CMSSDK` to `WebsiteSDK`.
+- Renamed the primary public options type from `CMSOptions` to `WebsiteSDKOptions`.
+- Renamed the primary config type from `ParsedCMSConfig` to `WebsiteSDKConfig`.
+- Changed the SDK error model from the legacy `CMSError` shape with `backend` to the core SDK error shape with `source`.
+- Changed CLI config files to use the same flat `WebsiteSDKConfig` shape.
+- Removed legacy stable-search helper exports from the root package API.
+- Removed legacy CMS construction and config type exports from the root package API.
+
+## Added
+
+- Added the `createWebsiteSDK` facade backed by `@v-office/sdk-core`.
+- Added `defineWebsiteSDKOptions`.
+- Added `WebsiteSDK`, `WebsiteSDKConfig`, and `WebsiteSDKOptions` public types.
+- Added top-level Effect helper exports for SDK operations.
+- Added top-level `submitPaymentOption` and `submitPaymentOptionEffect` exports.
+- Added public schemas from `@v-office/sdk-core`, including `GuestQuoteSchema`, `LocaleSchema`, `SearchSearchInputSchema`, and `SearchSearchOutputSchema`.
+- Added `rentalPropertyHighlightPrioritization` to `WebsiteSDKOptions`.
+- Added adapted instruction docs under `instructions/`.
+- Added version-specific release and migration docs under `instructions/versions/2.0.0/`.
+- Added an explicit package `types` entry for `./dist/index.d.mts`.
+
+## Preserved
+
+- Preserved the main SDK method tree:
+  - `sdk.static.rentals.getRentals`
+  - `sdk.static.filter.getFilters`
+  - `sdk.live.search.search`
+  - `sdk.live.availability.getInitialAvailability`
+  - `sdk.live.availability.getStartDateSelectedAvailability`
+  - `sdk.live.quote.*`
+  - `sdk.live.booking.book`
+  - `sdk.live.booking.submitPaymentOption`
+  - `sdk.live.contact.submit`
+  - `sdk.dispose`
+- Preserved `defineCMSSDKOptions` as an alias for `defineWebsiteSDKOptions`.
+- Preserved common legacy domain type aliases such as `BookingInput`, `BookingOutput`, `ContactInput`, `RentalRentalsInput`, `RentalRentalsOutput`, `RentalSearchInput`, and `RentalSearchOutput`.
+- Preserved v9 OpenAPI client exports.
+- Preserved v9 heuristic and v1 public API exports.
+- Preserved CLI environment variable names.
+
+## Release Notes
+
+- This is a major release for consumers migrating from the legacy website SDK API.
+- `@v-office/sdk-core` is now a runtime dependency. Ensure it is published or otherwise resolvable before publishing this package to a public registry.
+- The package remains ESM-only.

package/instructions/versions/2.0.0/MIGRATION.md

@@ -0,0 +1,223 @@
+# Migration: Legacy 1.x API to 2.0.0
+
+This guide covers the consumer-facing migration from the legacy CMS-style website SDK API to `@v-office/website-sdk` 2.0.0.
+
+## Source Version
+
+Legacy 1.x-style API:
+
+- `createCMSSDKFromParsedConfig`
+- `CMSSDK`
+- `CMSOptions`
+- `ParsedCMSConfig`
+- Nested `v9` / `v10` backend config objects
+
+## Target Version
+
+`@v-office/website-sdk` 2.0.0:
+
+- `createWebsiteSDK`
+- `WebsiteSDK`
+- `WebsiteSDKOptions`
+- `WebsiteSDKConfig`
+- Flat backend config object plus separate options
+
+## Package Import
+
+```ts
+import { createWebsiteSDK, defineWebsiteSDKOptions } from "@v-office/website-sdk";
+```
+
+The new package still exports `defineCMSSDKOptions` as an alias for `defineWebsiteSDKOptions`, but new code should use the Website naming.
+
+## SDK Creation
+
+Before:
+
+```ts
+import { createCMSSDKFromParsedConfig, defineCMSSDKOptions } from "@v-office/website-sdk";
+
+const sdk = createCMSSDKFromParsedConfig({
+  backend: "v10",
+  v10: {
+    apiEndpoint: "https://api.example.com/graphql",
+    accessToken: "...",
+    imageBaseUrl: "https://images.example.com",
+  },
+  options: defineCMSSDKOptions({
+    rentalScope: {
+      propertyId: "property-1",
+    },
+  }),
+});
+```
+
+After:
+
+```ts
+import { createWebsiteSDK, defineWebsiteSDKOptions } from "@v-office/website-sdk";
+
+const sdk = createWebsiteSDK({
+  config: {
+    backend: "v10",
+    apiEndpoint: "https://api.example.com/graphql",
+    accessToken: "...",
+    imageBaseUrl: "https://images.example.com",
+  },
+  options: defineWebsiteSDKOptions({
+    rentalScope: {
+      propertyId: "property-1",
+    },
+  }),
+});
+```
+
+## Config Shape
+
+Before:
+
+```ts
+{
+  backend: "v9",
+  v9: {
+    graphqlUrl: "...",
+    v1ApiBaseUrl: "...",
+    apiKey: "...",
+    imageProxyBaseUrl: "..."
+  },
+  options: {...}
+}
+```
+
+After:
+
+```ts
+createWebsiteSDK({
+  config: {
+    backend: "v9",
+    graphqlUrl: "...",
+    v1ApiBaseUrl: "...",
+    apiKey: "...",
+    imageProxyBaseUrl: "..."
+  },
+  options: {...}
+});
+```
+
+For v10, `backend: "v10"` is optional in TypeScript, but config files should include it when they are also used by the CLI.
+
+## Type Name Changes
+
+| Legacy                         | 2.0.0                     |
+| ------------------------------ | ------------------------- |
+| `CMSSDK`                       | `WebsiteSDK`              |
+| `CMSOptions`                   | `WebsiteSDKOptions`       |
+| `ParsedCMSConfig`              | `WebsiteSDKConfig`        |
+| `createCMSSDKFromParsedConfig` | `createWebsiteSDK`        |
+| `defineCMSSDKOptions`          | `defineWebsiteSDKOptions` |
+
+Several legacy domain aliases remain exported, including `BookingInput`, `BookingOutput`, `ContactInput`, `RentalRentalsInput`, `RentalRentalsOutput`, `RentalSearchInput`, and `RentalSearchOutput`.
+
+## Error Handling
+
+Legacy errors exposed `CMSError` with a `backend` field:
+
+```ts
+if (error instanceof CMSError && error.backend === "v9") {
+  // legacy handling
+}
+```
+
+2.0.0 aliases `CMSError` to `CoreSDKError` from `@v-office/sdk-core`. The error shape uses `source` instead of `backend`:
+
+```ts
+if (error instanceof CoreSDKError) {
+  console.error(error.source, error.operation, error.message);
+}
+```
+
+Audit any code that checks:
+
+- `error._tag`
+- `error.backend`
+- `error instanceof CMSError`
+- serialized SDK error payloads
+
+## CLI Migration
+
+Before:
+
+```json
+{
+  "backend": "v10",
+  "v10": {
+    "apiEndpoint": "https://api.example.com/graphql",
+    "accessToken": "...",
+    "imageBaseUrl": "https://images.example.com"
+  },
+  "options": {
+    "rentalScope": {
+      "propertyId": "property-1"
+    }
+  }
+}
+```
+
+After:
+
+```json
+{
+  "backend": "v10",
+  "apiEndpoint": "https://api.example.com/graphql",
+  "accessToken": "...",
+  "imageBaseUrl": "https://images.example.com"
+}
+```
+
+Move options into a separate file:
+
+```json
+{
+  "rentalScope": {
+    "propertyId": "property-1"
+  }
+}
+```
+
+Then run:
+
+```sh
+website-sdk --backend v10 --config ./website-sdk-config.json --options ./website-sdk-options.json rentals --locale de-DE
+```
+
+Environment variable names are unchanged.
+
+## Removed or Changed Exports
+
+The following legacy exports are not part of the 2.0.0 root API:
+
+- `createCMSSDKFromParsedConfig`
+- `CMSSDK`
+- `CMSOptions`
+- `ParsedCMSConfig`
+- `V9CMSConfig`
+- `V10CMSConfig`
+- `defineStableSearchInputGroup`
+- `toStableSearchInputParameterValues`
+- `toStableSearchInputQueryKeys`
+- `StableSearchInputGroup`
+- `GuestQuoteSelectionError`
+- v0 public schema helpers such as `V0OpenApiComponents`
+
+If a consuming app depends on any of these, migrate to the new names or keep a small local compatibility wrapper during the app migration.
+
+## Recommended Migration Steps
+
+1. Update imports to `@v-office/website-sdk`.
+2. Replace `createCMSSDKFromParsedConfig` calls with `createWebsiteSDK`.
+3. Convert nested backend config objects to flat `WebsiteSDKConfig` objects.
+4. Move embedded config `options` to the `options` argument.
+5. Rename explicit `CMS*` types to `Website*` types.
+6. Audit error handling.
+7. Update CLI config files and scripts.
+8. Run the consuming app's typecheck and a focused smoke test for rentals, search, quote, booking, and contact flows.

package/instructions/versions/2.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog: 2.1.0
+
+Release date: 2026-07-08
+
+This release extends the 2.0.0 website SDK facade without changing the flat config shape or main SDK construction API.
+
+## Added
+
+- Added v10 legal document access through `sdk.static.documents.getTermsAndPrivacyPolicy({ locale })` and `getTermsAndPrivacyPolicyEffect`.
+- Added `document-structured-json.md` instructions for legal document output and structured document rendering.
+- Added v10 contact submission through `messengeremail_newContactRequest`, with shared validation for v9 and v10 contact requests.
+- Added `validateContactSubmitInput`, `ContactSubmitValidationIssue`, and `ContactSubmitValidationIssueCode` exports.
+- Added v10 search voucher pricing via `SearchSearchInput.voucher` and CLI `--voucher`.
+- Added `quote.voucher` metadata for quoted voucher status.
+- Added v10 mapped `pets` search filter, exposed by `static.filter.getFilters` as a localized BooleanFilter.
+- Added backend-specific website SDK facade types such as `WebsiteSDKV9`, `WebsiteSDKV10`, `WebsiteSDKV10Static`, and `WebsiteSDKV10Live`.
+
+## Changed
+
+- v10 quote multi-rate handling now marks unavailable additional services and cancellation policies with `available: false` and `unavailableReason`.
+- Quote selection errors can now include `UnavailableQuoteCombination` when a selected add-on/policy combination cannot be priced.
+- Booking card sections now use a stable display order so included lines, selected add-ons, taxes, modifiers, and fallback sections render predictably.
+- Contact validation now rejects blank required fields, invalid email addresses, invalid country codes, and overly long values before backend submission.
+- v9 contact submission now uses the same core contact input and validation path as v10.
+
+## Migration Impact
+
+- No config migration is required from 2.0.0.
+- Existing search calls continue to work; use `voucher` only for v10 voucher pricing and use either `pets` or `petsCount`, not both.
+- Existing quote rendering should tolerate the new optional `voucher`, `available`, and `unavailableReason` fields.
+- Existing quote selection error handling should add a fallback for `UnavailableQuoteCombination`.
+- Existing contact forms should surface `CoreSDKError` validation issues from `error.cause.issues`.

package/instructions/versions/2.1.0/MIGRATION.md

@@ -0,0 +1,89 @@
+# Migration: 2.0.0 to 2.1.0
+
+This guide covers upgrading `@v-office/website-sdk` from 2.0.0 to 2.1.0.
+
+2.1.0 is a minor release. Keep using `createWebsiteSDK({ config, options })`, the flat `WebsiteSDKConfig`, and separate `WebsiteSDKOptions`.
+
+## What To Review
+
+### Documents
+
+v10 SDK instances now expose:
+
+```ts
+const documents = await sdk.static.documents.getTermsAndPrivacyPolicy({ locale: "de-DE" });
+```
+
+The output may contain `terms` and/or `privacyPolicy`, each with `{ subject, data }`. `data` is the published document revision data as a string. If your app renders this data, see `../../document-structured-json.md`.
+
+This API is v10-only. Code that handles both backends should narrow by `sdk.backend === "v10"` before calling `sdk.static.documents`.
+
+### Contact
+
+Contact requests are validated before submission on both v9 and v10. Validation failures reject with `CoreSDKError` using `operation: "contact.submit.validation"` and field details in `error.cause.issues`.
+
+Required fields are `title`, `surname`, `email`, `subject`, and `message`. Validation also checks email format, two-letter uppercase country codes, and maximum field lengths.
+
+Migration: update contact forms to display field-level validation issues instead of treating every contact error as a backend failure.
+
+### Search
+
+`SearchSearchInput` now accepts `voucher?: string` for v10 pricing:
+
+```ts
+await sdk.live.search.search({
+  locale: "de-DE",
+  query: "adults=2",
+  voucher: "SUMMER26",
+});
+```
+
+The CLI equivalent is `--voucher SUMMER26`.
+
+v10 filters now expose a mapped BooleanFilter with `searchParameterQueryKey: "pets"` and localized labels (`Dogs welcome` / `Hunde willkommen`). It maps to one pet in occupancy. Use either `pets` or `petsCount`, not both.
+
+### Quote
+
+Available quotes can include:
+
+```ts
+quote.voucher; // { code, status, message? }
+```
+
+`status` is `"applied"`, `"not_applied"`, or `"unknown"`. v10 can detect applied voucher modifiers; v9 uses `"unknown"` for available voucher quotes.
+
+Additional services and cancellation policies may now include:
+
+```ts
+{
+  available: false,
+  unavailableReason: "..."
+}
+```
+
+Migration: disable unavailable options in the UI and keep handling unknown optional fields gracefully.
+
+Quote selection errors can now include `UnavailableQuoteCombination` when a selected add-on/cancellation-policy combination cannot be priced. Add a generic message for unsupported combinations.
+
+### Public Types
+
+The root package now exports backend-specific facade types:
+
+- `WebsiteSDKV9`
+- `WebsiteSDKV10`
+- `WebsiteSDKSharedStatic`
+- `WebsiteSDKSharedLive`
+- `WebsiteSDKV10Static`
+- `WebsiteSDKV10Live`
+
+Use these only when you need backend-specific narrowing. Existing `WebsiteSDK` imports remain valid.
+
+## Recommended Steps
+
+1. Upgrade to `@v-office/website-sdk` 2.1.0.
+2. Update contact form error handling for `error.cause.issues`.
+3. If you render quotes, support optional `quote.voucher`, `available`, and `unavailableReason`.
+4. Add handling for `UnavailableQuoteCombination` in quote selection failures.
+5. If you use v10 search filters, render the new `pets` BooleanFilter and avoid combining it with `petsCount`.
+6. Use `sdk.static.documents.getTermsAndPrivacyPolicy` for v10 terms/privacy output where needed.
+7. Run a focused smoke test for search, quote selection, booking, contact submission, and v10 documents.