@v-office/website-sdk 2.0.0 → 2.1.0

package/instructions/creation.md

@@ -5,27 +5,27 @@
 Create the SDK with `createWebsiteSDK`:
 
 ```ts
-import { createWebsiteSDK, defineWebsiteSDKOptions } from '@v-office/website-sdk'
+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',
+    backend: "v10",
+    apiEndpoint: "https://api.example.com/graphql",
+    accessToken: "...",
+    imageBaseUrl: "https://images.example.com",
   },
   options: defineWebsiteSDKOptions({
     rentalScope: {
-      propertyId: 'property-1',
+      propertyId: "property-1",
     },
   }),
-})
+});
 
 try {
-  const rentals = await sdk.static.rentals.getRentals({ locale: 'de-DE' })
-  console.log(rentals)
+  const rentals = await sdk.static.rentals.getRentals({ locale: "de-DE" });
+  console.log(rentals);
 } finally {
-  await sdk.dispose()
+  await sdk.dispose();
 }
 ```
 
@@ -40,15 +40,15 @@ Backend config is required when creating the SDK.
 ```ts
 const sdk = createWebsiteSDK({
   config: {
-    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'],
+    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`:
@@ -56,12 +56,12 @@ const sdk = createWebsiteSDK({
 ```ts
 const sdk = createWebsiteSDK({
   config: {
-    backend: 'v10',
-    apiEndpoint: 'https://api.example.com/graphql',
-    accessToken: '...',
-    imageBaseUrl: 'https://images.example.com',
+    backend: "v10",
+    apiEndpoint: "https://api.example.com/graphql",
+    accessToken: "...",
+    imageBaseUrl: "https://images.example.com",
   },
-})
+});
 ```
 
 For v10, `backend: "v10"` is optional in TypeScript, but including it is clearer when config files are shared with the CLI.
@@ -73,25 +73,25 @@ For v10, `backend: "v10"` is optional in TypeScript, but including it is clearer
 ```ts
 const options = defineWebsiteSDKOptions({
   rentalScope: {
-    propertyId: 'property-1',
+    propertyId: "property-1",
   },
-  rentalHighlightPrioritization: ['bedrooms', 'bathrooms', 'maxPersons', 'wifi'],
-  rentalPropertyHighlightPrioritization: ['wifi', 'parking'],
+  rentalHighlightPrioritization: ["bedrooms", "bathrooms", "maxPersons", "wifi"],
+  rentalPropertyHighlightPrioritization: ["wifi", "parking"],
   customAttributeFilterDefinitions: [],
   translationOverrides: {},
-})
+});
 ```
 
 `defineWebsiteSDKOptions` is a typed identity helper. It is useful when defining options separately because TypeScript checks the option structure without changing the runtime value. `defineCMSSDKOptions` remains exported as a compatibility alias, but new code should use `defineWebsiteSDKOptions`.
 
 ```ts
 type WebsiteSDKOptions = {
-  translationOverrides?: TranslationOverrides
-  customAttributeFilterDefinitions?: readonly CustomAttributeFilterDefinition[]
-  rentalHighlightPrioritization?: readonly RentalHighlightPrioritizationKey[]
-  rentalPropertyHighlightPrioritization?: readonly RentalPropertyHighlightPrioritizationKey[]
-  rentalScope?: RentalScope
-}
+  translationOverrides?: TranslationOverrides;
+  customAttributeFilterDefinitions?: readonly CustomAttributeFilterDefinition[];
+  rentalHighlightPrioritization?: readonly RentalHighlightPrioritizationKey[];
+  rentalPropertyHighlightPrioritization?: readonly RentalPropertyHighlightPrioritizationKey[];
+  rentalScope?: RentalScope;
+};
 ```
 
 Unset options are normalized by the SDK:
@@ -109,9 +109,9 @@ Use `rentalScope` to restrict all rental lists and searches created by this SDK
 ```ts
 const options = defineWebsiteSDKOptions({
   rentalScope: {
-    propertyId: 'property-1',
+    propertyId: "property-1",
   },
-})
+});
 ```
 
 `propertyId` is a unified SDK option:
@@ -130,20 +130,20 @@ Use `customAttributeFilterDefinitions` to add SDK-known filter keys for custom a
 const options = defineWebsiteSDKOptions({
   customAttributeFilterDefinitions: [
     {
-      key: 'region',
-      source: 'customAttribute',
-      category: 'ESSENTIALS',
+      key: "region",
+      source: "customAttribute",
+      category: "ESSENTIALS",
       label: {
-        'de-DE': 'Region',
-        'en-US': 'Region',
+        "de-DE": "Region",
+        "en-US": "Region",
       },
-      type: 'option',
+      type: "option",
       options: [
         {
-          value: 'north',
+          value: "north",
           label: {
-            'de-DE': 'Nord',
-            'en-US': 'North',
+            "de-DE": "Nord",
+            "en-US": "North",
           },
         },
       ],
@@ -151,7 +151,7 @@ const options = defineWebsiteSDKOptions({
       internal: false,
     },
   ],
-})
+});
 ```
 
 Supported filter types:
@@ -181,11 +181,11 @@ Use `translationOverrides` to override SDK translation keys:
 ```ts
 const options = defineWebsiteSDKOptions({
   translationOverrides: {
-    'de-DE': {
-      'filter.wifi.label': 'WLAN',
+    "de-DE": {
+      "filter.wifi.label": "WLAN",
     },
   },
-})
+});
 ```
 
 Overrides are applied by the SDK translation service and affect labels generated by filters, rentals, search, availability, and quote output.

package/instructions/document-structured-json.md

@@ -0,0 +1,100 @@
+# Structured Document JSON
+
+## Service
+
+Use the v10 static documents API to fetch published terms and privacy policy revisions:
+
+```ts
+if (sdk.backend === "v10") {
+  const documents = await sdk.static.documents.getTermsAndPrivacyPolicy({ locale: "de-DE" });
+}
+```
+
+Input is `{ locale: "de-DE" | "en-US" }`. Output is `Promise<DocumentsGetTermsAndPrivacyPolicyOutput>` with optional `terms` and `privacyPolicy`, each shaped as `{ subject, data }`.
+
+This API is v10-only, has no dedicated CLI command yet, and returns `data` as a string. When `data` contains structured document JSON, render it with the rules below.
+
+## At A Glance
+
+The document is a JSON array. Each item is either plain text or a structured tool object.
+
+```json
+[
+  "plain text",
+  "\n",
+  {
+    "tool": "link",
+    "settings": { "href": "https://example.com" },
+    "children": [{ "tool": "bold", "children": ["Example"] }]
+  }
+]
+```
+
+## Base Rules
+
+- Root value: always an array. An empty document is `[]`.
+- Text part: any JSON string. `"\n"` means a line break. A string may also contain embedded `\n`.
+- Tool part: `{ "tool": string, "settings"?: object, "children"?: array }`.
+- `tool`: required name that defines how to interpret `settings` and `children`.
+- `settings`: optional metadata object. Omit it when unused; do not rely on `null`.
+- `children`: optional nested document array with the same shape as the root.
+- Unknown tools have no standard meaning. Preserve them when round-tripping; skip or fallback gracefully when rendering.
+- Internal cursor/selection marker tools are editor state, not document content, and should not be stored.
+
+## Tool Sets
+
+A document may use any subset of these tools. Custom producers may add more tool names.
+
+## Built-In Tool Reference
+
+- `bold`, `italic`, `underline`: formatting wrappers with `children`.
+- `color`: `settings.textColor`; optional `settings.backgroundColor`; has `children`.
+- `leading`: `settings.leading`; values: `tight`, `snug`, `normal`, `relaxed`, `loose`; has `children`.
+- `alignment`: `settings.alignment`; values: `left`, `center`, `right`, `justify`; has `children`.
+- `headline`: `settings.level` from `1` to `6`; has `children`.
+- `horizontalLine`: no settings or children.
+- `list`: `settings.numbered`; `children` are `item` tool objects.
+- `item`: structural list item; meaningful inside `list`; uses `children`.
+- `table`: `settings.headRows`, `settings.headColumns`; `children` are `row` tool objects.
+- `row`: structural table row; meaningful inside `table`; `children` are `column` tool objects.
+- `column`: structural table cell; meaningful inside `row`; uses `children`.
+- `link`: `settings.href`; optional `settings.embedded` with `type` and `size`; non-embedded links use `children`.
+- `image`: `settings.url`; optional `settings.caption`, `settings.cid`.
+- `placeholder`: `settings.domain`, `settings.field`, `settings.type`; renders as `{{domain.field}}` in reading mode.
+- `conditional`: `settings.service`, `settings.conditions[]` with `{ "condition": string, "fields": object }`; has conditional `children`.
+- `snippet`: `settings.service`, `settings.topLevelEntity`, `settings.snippet`, `settings.config`; optional `settings.inline`.
+- `ai`: optional `settings.prompt`, `settings.loadingText`; optional replacement `children`; reading mode renders empty text.
+- `quote`: optional `settings.author`, `settings.datetime`, `settings.messengerId`, `settings.html`; treat HTML as untrusted and sanitize before rendering.
+- `knowledgeBaseReference`: `settings.key`; has `children`.
+- `knowledgeBaseLink`: `settings.articleId`; has `children`.
+- `alert`: `settings.type`; values: `info`, `success`, `warning`, `error`; has `children`.
+- `code`: `settings.code`; optional `settings.block`, `settings.language`.
+
+Link embed `type` values: `youtube`, `figmaFile`, `figmaDesign`, `figmaBoard`, `heygen`, `heygenEmbeds`, `synthesia`, `iframe`.
+
+Link embed `size` values: `small`, `medium`, `large`.
+
+Code `language` values: `typescript`, `javascript`, `xml`, `json`, `yaml`, `css`, `graphql`.
+
+## Edge Cases
+
+- Missing `children` and empty `children: []` both mean no nested content.
+- Missing `settings` is valid only when the tool has no required settings.
+- Some tools ignore `children` even if present, for example `image`, `code`, `quote`, `snippet`, and embedded `link`.
+- `placeholder`, `conditional`, `snippet`, and `knowledgeBaseLink` need external application context to render fully.
+- `conditional.children` should only be displayed when its conditions pass.
+- `snippet` content is rendered from `settings` by an external renderer, not stored in `children`.
+- `quote.settings.html` can contain HTML; consumers should sanitize it even if it was already sanitized by the producer.
+- `ai` is transient editing state. Consumers that render final read-only content should treat it as empty.
+- `cid` on `image` may reference an attached resource instead of using only `url`.
+- Structural tools `item`, `row`, and `column` are not meaningful as top-level document blocks.
+
+## Compact Examples
+
+```json
+{ "tool": "headline", "settings": { "level": 2 }, "children": ["Heading"] }
+{ "tool": "list", "settings": { "numbered": false }, "children": [{ "tool": "item", "children": ["Item"] }] }
+{ "tool": "image", "settings": { "url": "https://example.com/image.png", "caption": "Optional" } }
+{ "tool": "placeholder", "settings": { "domain": "User", "field": "email", "type": "string" } }
+{ "tool": "code", "settings": { "block": true, "language": "typescript", "code": "const value = 1" } }
+```

package/instructions/filter.md

@@ -5,7 +5,7 @@
 Use the static filter API to fetch localized search filter definitions:
 
 ```ts
-const filters = await sdk.static.filter.getFilters({ locale: 'de-DE' })
+const filters = await sdk.static.filter.getFilters({ locale: "de-DE" });
 ```
 
 The service is implemented for both `v9` and `v10` backends and returns normalized filters for building search UIs.
@@ -14,8 +14,8 @@ The service is implemented for both `v9` and `v10` backends and returns normaliz
 
 ```ts
 type FilterGetFiltersInput = {
-  locale: 'de-DE' | 'en-US'
-}
+  locale: "de-DE" | "en-US";
+};
 ```
 
 Sample:
@@ -129,6 +129,8 @@ Optional `WebsiteSDKOptions` can add public custom filters:
 
 Only custom definitions with `searchable: true` and `internal: false` are exposed by `getFilters`.
 
+For v10, `getFilters` also exposes the mapped BooleanFilter `pets`, labeled `Dogs welcome` / `Hunde willkommen`. It maps to one pet in search occupancy; use `petsCount` when the UI needs an exact pet count instead.
+
 ## CLI Usage
 
 Fetch filters with environment-based config:

package/instructions/quote.md

@@ -5,36 +5,36 @@
 Use the live quote API to price a stay and get selectable booking options:
 
 ```ts
-const result = await sdk.live.quote.quote(input)
+const result = await sdk.live.quote.quote(input);
 ```
 
 If the quote is available, the returned `GuestQuote` can be updated through selection helpers:
 
 ```ts
-const withService = await sdk.live.quote.addAdditionalService({ quote, id: 'linen' })
-const withPolicy = await sdk.live.quote.selectCancellationPolicy({ quote, id: 'alternative' })
+const withService = await sdk.live.quote.addAdditionalService({ quote, id: "linen" });
+const withPolicy = await sdk.live.quote.selectCancellationPolicy({ quote, id: "alternative" });
 ```
 
 ## Input
 
 ```ts
 type QuoteQuoteInput = {
-  locale: 'de-DE' | 'en-US'
-  rentalId: string
+  locale: "de-DE" | "en-US";
+  rentalId: string;
   period: {
-    start: string
-    end: string
-  }
+    start: string;
+    end: string;
+  };
   occupancy: {
-    adults: number
-    children: number
-    childrenAges?: number[]
-    babies: number
-    pets: number
-  }
-  destinationCountryCode?: string
-  voucher?: string
-}
+    adults: number;
+    children: number;
+    childrenAges?: number[];
+    babies: number;
+    pets: number;
+  };
+  destinationCountryCode?: string;
+  voucher?: string;
+};
 ```
 
 `GuestQuoteInput` remains available as a legacy alias.
@@ -62,6 +62,7 @@ Sample:
 ```
 
 Dates are local dates formatted as `YYYY-MM-DD`. For `v9`, `rentalId` must be a numeric vOffice unit id.
+Both backends accept `voucher` on quote and booking flows. `v10` can expose voucher discounts as booking-card modifiers when the backend returns voucher modifiers; `v9` reflects voucher effects in the quoted totals but does not expose a separate voucher modifier line.
 
 ## Output
 
@@ -88,6 +89,11 @@ Available sample:
       ],
       "total": "1,200.00 EUR"
     },
+    "voucher": {
+      "code": "SUMMER26",
+      "status": "applied",
+      "message": "The voucher code was applied."
+    },
     "additionalServices": [
       {
         "id": "linen",
@@ -131,7 +137,23 @@ Unavailable sample:
 }
 ```
 
-Selection methods return `{ ok: true, quote }` or `{ ok: false, error }`. Possible selection errors include unknown additional service, additional service limit exceeded, unknown cancellation policy, and unavailable cancellation policy quote.
+Selection methods return `{ ok: true, quote }` or `{ ok: false, error }`. Possible selection errors include unknown additional service, additional service limit exceeded, unknown cancellation policy, unavailable cancellation policy quote, and unavailable quote combination.
+
+## Vouchers
+
+When `voucher` is provided in the quote input, an available quote may include `quote.voucher`:
+
+```json
+{
+  "code": "SUMMER26",
+  "status": "applied",
+  "message": "The voucher code was applied."
+}
+```
+
+`status` is `"applied"`, `"not_applied"`, or `"unknown"`. `v10` reports `"applied"` when the backend returns a non-zero voucher modifier and `"not_applied"` when no voucher modifier is returned for the requested voucher. `v9` returns `"unknown"` for available voucher quotes because the legacy response does not provide a reliable voucher modifier signal.
+
+Voucher modifiers can appear in `bookingCardInformation.sections`. Sections are returned in display order.
 
 ## Additional Services
 
@@ -142,6 +164,7 @@ Additional services are exposed on an available quote as `quote.additionalServic
   "id": "linen",
   "label": "Bed linen",
   "charge": "25.00 EUR",
+  "available": true,
   "maxPerBooking": 1,
   "description": "Bed linen package"
 }
@@ -150,17 +173,17 @@ Additional services are exposed on an available quote as `quote.additionalServic
 Use the service `id` to add or remove a service selection:
 
 ```ts
-const added = await sdk.live.quote.addAdditionalService({ quote, id: 'linen' })
-if (added.ok) quote = added.quote
+const added = await sdk.live.quote.addAdditionalService({ quote, id: "linen" });
+if (added.ok) quote = added.quote;
 
-const removed = await sdk.live.quote.removeAdditionalService({ quote, id: 'linen' })
-if (removed.ok) quote = removed.quote
+const removed = await sdk.live.quote.removeAdditionalService({ quote, id: "linen" });
+if (removed.ok) quote = removed.quote;
 
-const cleared = await sdk.live.quote.clearAdditionalServices({ quote })
-if (cleared.ok) quote = cleared.quote
+const cleared = await sdk.live.quote.clearAdditionalServices({ quote });
+if (cleared.ok) quote = cleared.quote;
 ```
 
-Each successful change returns a new quote with recalculated `bookingCardInformation.total`. Handle `{ ok: false, error }` for unknown service ids or quantity limits.
+Each successful change returns a new quote with recalculated `bookingCardInformation.total`. v10 can mark unavailable service/policy combinations with `available: false` and `unavailableReason`; disable those options in the UI. Handle `{ ok: false, error }` for unknown service ids, quantity limits, or `UnavailableQuoteCombination`.
 
 ## Cancellation Policies
 
@@ -171,6 +194,7 @@ Cancellation policies are exposed on `quote.cancellationPolicies` when the backe
   "id": "alternative",
   "label": "Flexible cancellation",
   "selected": false,
+  "available": true,
   "markUpPercentage": "10%",
   "processingFee": "25.00 EUR",
   "rules": [
@@ -187,10 +211,10 @@ Select a policy by id:
 ```ts
 const selected = await sdk.live.quote.selectCancellationPolicy({
   quote,
-  id: 'alternative',
-})
+  id: "alternative",
+});
 
-if (selected.ok) quote = selected.quote
+if (selected.ok) quote = selected.quote;
 ```
 
 The selected policy is marked with `selected: true`, and the booking card total is recalculated if the policy changes the price. Handle selection errors for unknown or unavailable policy ids.
@@ -228,18 +252,18 @@ Use `selectInsurance` to choose no insurance or a product:
 quote = await sdk.live.quote.selectInsurance({
   quote,
   selection: {
-    kind: 'insurance',
-    id: 'ergo',
+    kind: "insurance",
+    id: "ergo",
     travelers: [
       {
-        salutation: 'Ms',
-        forename: 'Jane',
-        surname: 'Doe',
-        birthday: '1990-01-01',
+        salutation: "Ms",
+        forename: "Jane",
+        surname: "Doe",
+        birthday: "1990-01-01",
       },
     ],
   },
-})
+});
 ```
 
 For insurance products that require a pre-contract, provide customer information:
@@ -248,18 +272,18 @@ For insurance products that require a pre-contract, provide customer information
 quote = await sdk.live.quote.createInsurancePreContract({
   quote,
   customerInformation: {
-    destinationCountryCode: 'DE',
+    destinationCountryCode: "DE",
     address: {
-      street: 'Main Street',
-      housenumber: '1',
-      postalcode: '12345',
-      city: 'Berlin',
-      countryCode: 'DE',
+      street: "Main Street",
+      housenumber: "1",
+      postalcode: "12345",
+      city: "Berlin",
+      countryCode: "DE",
     },
-    email: 'jane@example.com',
-    mobile: '+49123456789',
+    email: "jane@example.com",
+    mobile: "+49123456789",
   },
-})
+});
 ```
 
 Select an insurance payment method before booking insurance:
@@ -268,10 +292,10 @@ Select an insurance payment method before booking insurance:
 quote = await sdk.live.quote.selectInsurancePayment({
   quote,
   paymentInformation: {
-    kind: 'sepa_debit',
-    iban: 'DE02120300000000202051',
+    kind: "sepa_debit",
+    iban: "DE02120300000000202051",
   },
-})
+});
 ```
 
 After the rental booking is created, complete insurance booking with the booking number and guest token:
@@ -281,7 +305,7 @@ const insuranceBooking = await sdk.live.quote.bookInsurance({
   quote,
   bookingNumber: booking.bookingNumber,
   guestToken: booking.guestToken,
-})
+});
 ```
 
 `v9` supports real insurance option refresh, pre-contract, payment selection, and booking. `v10` currently returns a no-insurance placeholder and insurance actions resolve as not required.

package/instructions/rentals.md

@@ -5,7 +5,7 @@
 Use the static rentals API to fetch localized rental summaries:
 
 ```ts
-const rentals = await sdk.static.rentals.getRentals({ locale: 'de-DE' })
+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.
@@ -14,8 +14,8 @@ The service is implemented for both `v9` and `v10` backends and returns one norm
 
 ```ts
 type RentalRentalsInput = {
-  locale: 'de-DE' | 'en-US'
-}
+  locale: "de-DE" | "en-US";
+};
 ```
 
 Sample: