@v-office/website-sdk 1.2.1 → 2.0.0

package/dist/instructions/rentals.md

@@ -0,0 +1,152 @@
+# Rentals
+
+## Service
+
+Use the static rentals API to fetch localized rental summaries:
+
+```ts
+const rentals = await sdk.static.rentals.getRentals({ locale: 'de-DE' })
+```
+
+The service is implemented for both `v9` and `v10` backends and returns one normalized item per rental.
+
+## Input
+
+```ts
+type RentalRentalsInput = {
+  locale: 'de-DE' | 'en-US'
+}
+```
+
+Sample:
+
+```json
+{
+  "locale": "de-DE"
+}
+```
+
+## Output
+
+Returns `Promise<RentalGetRentalsOutput>`. The package also exports the legacy alias `RentalRentalsOutput` for a single rental item.
+
+Sample item:
+
+```json
+{
+  "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"
+    }
+  ],
+  "description": {
+    "headline": "Holiday apartment near the sea",
+    "description": "Short localized rental description."
+  },
+  "highlights": ["2 bedrooms", "WiFi", "Parking"],
+  "attributes": [
+    {
+      "label": "Amenities",
+      "subCategories": [
+        {
+          "label": "Kitchen",
+          "items": ["Dishwasher", "Oven"]
+        }
+      ]
+    }
+  ],
+  "reviews": {
+    "items": [
+      {
+        "rating": "5",
+        "author": "Jane",
+        "text": "Great stay."
+      }
+    ],
+    "summary": {
+      "rating": "4.8",
+      "count": "12",
+      "classification": "Excellent"
+    }
+  }
+}
+```
+
+Optional fields include `scope`, `address`, `property`, `rooms`, `roomSummary`, `vicinity`, and `reviews`.
+
+## Configuration
+
+`v9` config:
+
+```json
+{
+  "backend": "v9",
+  "graphqlUrl": "https://example.com/graphql",
+  "v1ApiBaseUrl": "https://example.com/api/v1",
+  "v0ApiBaseUrl": "https://example.com/api/v0",
+  "apiKey": "...",
+  "imageProxyBaseUrl": "https://images.example.com",
+  "rentalDataAttributes": ["name", "description"]
+}
+```
+
+`v10` config:
+
+```json
+{
+  "backend": "v10",
+  "apiEndpoint": "https://api.example.com/graphql",
+  "accessToken": "...",
+  "imageBaseUrl": "https://images.example.com"
+}
+```
+
+Optional `WebsiteSDKOptions`:
+
+```json
+{
+  "rentalHighlightPrioritization": ["bedrooms", "bathrooms", "maxPersons", "wifi"],
+  "rentalPropertyHighlightPrioritization": ["wifi", "parking"],
+  "customAttributeFilterDefinitions": [],
+  "translationOverrides": {}
+}
+```
+
+`rentalHighlightPrioritization` controls the order of rental `highlights`. `rentalPropertyHighlightPrioritization` controls property highlights for v10 property data. Custom attribute definitions can add custom values to rental output. Translation overrides affect localized labels.
+
+## CLI Usage
+
+Fetch rentals with environment-based config:
+
+```sh
+website-sdk --backend v9 rentals --locale en-US
+website-sdk --backend v10 rentals --locale de-DE
+```
+
+Use files instead of environment variables:
+
+```sh
+website-sdk --backend v10 --config ./website-sdk-config.json --options ./website-sdk-options.json rentals --locale de-DE
+```
+
+Output defaults to JSON. Use `--output pretty` for inspected terminal output:
+
+```sh
+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`.

package/dist/instructions/search.md

@@ -0,0 +1,233 @@
+# 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[]
+  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"],
+  "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.
+
+`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 with `--rental-ids-in` (`v10` only):
+
+```sh
+website-sdk --backend v10 search --locale de-DE --query "adults=2" --rental-ids-in "123,456"
+```
+
+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/dist/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/dist/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.