@v-office/website-sdk 1.2.1 → 2.0.0

package/instructions/creation.md

@@ -0,0 +1,223 @@
+# Creation
+
+## Service
+
+Create the SDK with `createWebsiteSDK`:
+
+```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',
+    },
+  }),
+})
+
+try {
+  const rentals = await sdk.static.rentals.getRentals({ locale: 'de-DE' })
+  console.log(rentals)
+} finally {
+  await sdk.dispose()
+}
+```
+
+`createWebsiteSDK` returns the public `WebsiteSDK` facade with `static`, `live`, and `dispose` APIs. Call `dispose()` when the SDK instance is no longer needed. For v9, `dispose()` currently resolves without tearing down shared runtime state because the v9 facade does not hold one.
+
+## Configuration
+
+Backend config is required when creating the SDK.
+
+`v9`:
+
+```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'],
+  },
+})
+```
+
+`v10`:
+
+```ts
+const sdk = createWebsiteSDK({
+  config: {
+    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.
+
+## WebsiteSDKOptions
+
+`options` is optional and is passed separately from backend config:
+
+```ts
+const options = defineWebsiteSDKOptions({
+  rentalScope: {
+    propertyId: 'property-1',
+  },
+  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
+}
+```
+
+Unset options are normalized by the SDK:
+
+- `customAttributeFilterDefinitions` defaults to `[]`.
+- `rentalHighlightPrioritization` defaults to the SDK default rental highlight order.
+- `rentalPropertyHighlightPrioritization` defaults to the SDK default property highlight order.
+- `rentalScope` defaults to `{}`.
+- `translationOverrides` is omitted unless provided.
+
+## Rental Scope
+
+Use `rentalScope` to restrict all rental lists and searches created by this SDK instance:
+
+```ts
+const options = defineWebsiteSDKOptions({
+  rentalScope: {
+    propertyId: 'property-1',
+  },
+})
+```
+
+`propertyId` is a unified SDK option:
+
+- `v9` static rentals are filtered by `voffice_facility_id`.
+- `v9` live search maps it to the generated `VofficeFilter.falicityid` field.
+- `v10` static rentals and live search map it to the generated `rentals_RentalSummaryFilter.propertyId` field.
+
+The scope is always applied internally and is not returned by `static.filter.getFilters(...)`. Use it for website-level or tenant-level constraints.
+
+## Custom Attribute Filter Definitions
+
+Use `customAttributeFilterDefinitions` to add SDK-known filter keys for custom attributes, v9 backend filters, or composed filters:
+
+```ts
+const options = defineWebsiteSDKOptions({
+  customAttributeFilterDefinitions: [
+    {
+      key: 'region',
+      source: 'customAttribute',
+      category: 'ESSENTIALS',
+      label: {
+        'de-DE': 'Region',
+        'en-US': 'Region',
+      },
+      type: 'option',
+      options: [
+        {
+          value: 'north',
+          label: {
+            'de-DE': 'Nord',
+            'en-US': 'North',
+          },
+        },
+      ],
+      searchable: true,
+      internal: false,
+    },
+  ],
+})
+```
+
+Supported filter types:
+
+- `boolean`: accepts enabled query values such as `?key`, `?key=true`, or `?key=1`.
+- `int`: accepts integer query values and can expose optional `numericBounds` for UI controls.
+- `option`: accepts one of the configured `options` values and exposes those options through `getFilters`.
+- `string`: accepts any non-empty query value as an exact raw value.
+- `complex`: composition-only type that expands one boolean query-string filter into other configured filters.
+
+Supported sources:
+
+- `customAttribute`: backed by custom attributes.
+- `backendFilter`: backed by backend-defined search filter keys, mainly for v9 hub filters.
+- `composition`: expands one boolean query-string filter into other configured filters.
+
+Visibility:
+
+- `internal: false` exposes searchable filters through `static.filter.getFilters(...)`.
+- `internal: true` keeps filters usable by search and compositions but hides them from `getFilters`.
+- `searchable: false` keeps custom attributes as display metadata only.
+
+## Translation Overrides
+
+Use `translationOverrides` to override SDK translation keys:
+
+```ts
+const options = defineWebsiteSDKOptions({
+  translationOverrides: {
+    '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.
+
+## CLI Usage
+
+The CLI reads flat `WebsiteSDKConfig` JSON files and separate `WebsiteSDKOptions` JSON files:
+
+```sh
+website-sdk --backend v10 --config ./website-sdk-config.json --options ./website-sdk-options.json rentals --locale de-DE
+```
+
+Example `website-sdk-config.v10.json`:
+
+```json
+{
+  "backend": "v10",
+  "apiEndpoint": "https://api.example.com/graphql",
+  "accessToken": "...",
+  "imageBaseUrl": "https://images.example.com"
+}
+```
+
+Example `website-sdk-options.json`:
+
+```json
+{
+  "rentalScope": {
+    "propertyId": "property-1"
+  },
+  "rentalHighlightPrioritization": ["bedrooms", "bathrooms", "maxPersons", "wifi"],
+  "customAttributeFilterDefinitions": [],
+  "translationOverrides": {}
+}
+```

package/instructions/filter.md

@@ -0,0 +1,156 @@
+# Filter
+
+## Service
+
+Use the static filter API to fetch localized search filter definitions:
+
+```ts
+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.
+
+## Input
+
+```ts
+type FilterGetFiltersInput = {
+  locale: 'de-DE' | 'en-US'
+}
+```
+
+Sample:
+
+```json
+{
+  "locale": "de-DE"
+}
+```
+
+## Output
+
+Returns `Promise<FilterGetFiltersOutput>`, an array of filter definitions.
+
+Sample:
+
+```json
+[
+  {
+    "searchParameterQueryKey": "wifi",
+    "label": "WiFi",
+    "category": "ESSENTIALS",
+    "type": "BooleanFilter"
+  },
+  {
+    "searchParameterQueryKey": "bedrooms",
+    "label": "Bedrooms",
+    "category": "ROOMS",
+    "type": "IntFilter",
+    "numericBounds": {
+      "min": 1,
+      "max": 8
+    }
+  },
+  {
+    "searchParameterQueryKey": "region",
+    "label": "Region",
+    "category": "LOCATION",
+    "type": "OptionFilter",
+    "options": [
+      {
+        "value": "north",
+        "label": "North"
+      }
+    ]
+  }
+]
+```
+
+Filter variants:
+
+- `BooleanFilter`: on/off query parameter.
+- `IntFilter`: numeric query parameter, optionally with `numericBounds`.
+- `OptionFilter`: query parameter with localized selectable `options`.
+
+## Configuration
+
+`v9` config:
+
+```json
+{
+  "backend": "v9",
+  "graphqlUrl": "https://example.com/graphql",
+  "v1ApiBaseUrl": "https://example.com/api/v1",
+  "apiKey": "...",
+  "imageProxyBaseUrl": "https://images.example.com"
+}
+```
+
+`v10` config:
+
+```json
+{
+  "backend": "v10",
+  "apiEndpoint": "https://api.example.com/graphql",
+  "accessToken": "...",
+  "imageBaseUrl": "https://images.example.com"
+}
+```
+
+Optional `WebsiteSDKOptions` can add public custom filters:
+
+```json
+{
+  "customAttributeFilterDefinitions": [
+    {
+      "key": "region",
+      "source": "customAttribute",
+      "category": "ESSENTIALS",
+      "label": {
+        "de-DE": "Region",
+        "en-US": "Region"
+      },
+      "type": "option",
+      "options": [
+        {
+          "value": "north",
+          "label": {
+            "de-DE": "Norden",
+            "en-US": "North"
+          }
+        }
+      ],
+      "searchable": true,
+      "internal": false
+    }
+  ],
+  "translationOverrides": {}
+}
+```
+
+Only custom definitions with `searchable: true` and `internal: false` are exposed by `getFilters`.
+
+## CLI Usage
+
+Fetch filters with environment-based config:
+
+```sh
+website-sdk --backend v9 filters --locale en-US
+website-sdk --backend v10 filters --locale de-DE
+```
+
+Use files instead of environment variables:
+
+```sh
+website-sdk --backend v10 --config ./website-sdk-config.json --options ./website-sdk-options.json filters --locale de-DE
+```
+
+Output defaults to JSON. Use `--output pretty` for inspected terminal output:
+
+```sh
+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`.

package/instructions/quote.md

@@ -0,0 +1,318 @@
+# Quote
+
+## Service
+
+Use the live quote API to price a stay and get selectable booking options:
+
+```ts
+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' })
+```
+
+## Input
+
+```ts
+type QuoteQuoteInput = {
+  locale: 'de-DE' | 'en-US'
+  rentalId: string
+  period: {
+    start: string
+    end: string
+  }
+  occupancy: {
+    adults: number
+    children: number
+    childrenAges?: number[]
+    babies: number
+    pets: number
+  }
+  destinationCountryCode?: string
+  voucher?: string
+}
+```
+
+`GuestQuoteInput` remains available as a legacy alias.
+
+Sample:
+
+```json
+{
+  "locale": "de-DE",
+  "rentalId": "123",
+  "period": {
+    "start": "2026-07-01",
+    "end": "2026-07-08"
+  },
+  "occupancy": {
+    "adults": 2,
+    "children": 1,
+    "childrenAges": [8],
+    "babies": 0,
+    "pets": 1
+  },
+  "destinationCountryCode": "DE",
+  "voucher": "SUMMER26"
+}
+```
+
+Dates are local dates formatted as `YYYY-MM-DD`. For `v9`, `rentalId` must be a numeric vOffice unit id.
+
+## Output
+
+Returns `Promise<GuestQuoteResult>`.
+
+Available sample:
+
+```json
+{
+  "status": "available",
+  "quote": {
+    "bookingCardInformation": {
+      "sections": [
+        {
+          "lines": [
+            {
+              "item": {
+                "position": "Rent",
+                "appliedCharge": "1,200.00 EUR"
+              }
+            }
+          ]
+        }
+      ],
+      "total": "1,200.00 EUR"
+    },
+    "additionalServices": [
+      {
+        "id": "linen",
+        "label": "Bed linen",
+        "charge": "25.00 EUR",
+        "maxPerBooking": 1
+      }
+    ],
+    "cancellationPolicies": [
+      {
+        "id": "default",
+        "label": "Default cancellation policy",
+        "selected": true
+      }
+    ],
+    "insurance": {
+      "options": [
+        {
+          "kind": "none",
+          "label": "No insurance"
+        }
+      ],
+      "selected": {
+        "kind": "none"
+      },
+      "preContract": {
+        "kind": "none_selected"
+      },
+      "paymentOptions": []
+    }
+  }
+}
+```
+
+Unavailable sample:
+
+```json
+{
+  "status": "unavailable",
+  "reason": "Rental is not available for the selected period."
+}
+```
+
+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.
+
+## Additional Services
+
+Additional services are exposed on an available quote as `quote.additionalServices`.
+
+```json
+{
+  "id": "linen",
+  "label": "Bed linen",
+  "charge": "25.00 EUR",
+  "maxPerBooking": 1,
+  "description": "Bed linen package"
+}
+```
+
+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 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
+```
+
+Each successful change returns a new quote with recalculated `bookingCardInformation.total`. Handle `{ ok: false, error }` for unknown service ids or quantity limits.
+
+## Cancellation Policies
+
+Cancellation policies are exposed on `quote.cancellationPolicies` when the backend offers selectable policies.
+
+```json
+{
+  "id": "alternative",
+  "label": "Flexible cancellation",
+  "selected": false,
+  "markUpPercentage": "10%",
+  "processingFee": "25.00 EUR",
+  "rules": [
+    {
+      "daysBeforeArrival": 14,
+      "refundPercentage": "80%"
+    }
+  ]
+}
+```
+
+Select a policy by id:
+
+```ts
+const selected = await sdk.live.quote.selectCancellationPolicy({
+  quote,
+  id: 'alternative',
+})
+
+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.
+
+## Insurance
+
+Insurance information is exposed on `quote.insurance` when available. The `options` array contains either a `none` option or selectable insurance products.
+
+```json
+{
+  "options": [
+    {
+      "kind": "insurance",
+      "id": "ergo",
+      "formattedPrice": "49.00 EUR",
+      "label": "Travel cancellation insurance",
+      "requiredInformation": {
+        "kind": "travelers"
+      }
+    }
+  ],
+  "selected": {
+    "kind": "none"
+  },
+  "preContract": {
+    "kind": "none_selected"
+  },
+  "paymentOptions": []
+}
+```
+
+Use `selectInsurance` to choose no insurance or a product:
+
+```ts
+quote = await sdk.live.quote.selectInsurance({
+  quote,
+  selection: {
+    kind: 'insurance',
+    id: 'ergo',
+    travelers: [
+      {
+        salutation: 'Ms',
+        forename: 'Jane',
+        surname: 'Doe',
+        birthday: '1990-01-01',
+      },
+    ],
+  },
+})
+```
+
+For insurance products that require a pre-contract, provide customer information:
+
+```ts
+quote = await sdk.live.quote.createInsurancePreContract({
+  quote,
+  customerInformation: {
+    destinationCountryCode: 'DE',
+    address: {
+      street: 'Main Street',
+      housenumber: '1',
+      postalcode: '12345',
+      city: 'Berlin',
+      countryCode: 'DE',
+    },
+    email: 'jane@example.com',
+    mobile: '+49123456789',
+  },
+})
+```
+
+Select an insurance payment method before booking insurance:
+
+```ts
+quote = await sdk.live.quote.selectInsurancePayment({
+  quote,
+  paymentInformation: {
+    kind: 'sepa_debit',
+    iban: 'DE02120300000000202051',
+  },
+})
+```
+
+After the rental booking is created, complete insurance booking with the booking number and guest token:
+
+```ts
+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.
+
+## Configuration
+
+Quote requests are rate-limited to one backend request per second with a queue size of five. `v9` supports insurance option refresh and insurance actions; `v10` currently returns a no-insurance placeholder and insurance actions resolve as not required.
+
+## CLI Usage
+
+Create `quote-input.json` with a `QuoteQuoteInput` object, then run:
+
+```sh
+website-sdk --backend v10 quote --input ./quote-input.json
+```
+
+Use files instead of environment variables:
+
+```sh
+website-sdk --backend v9 --config ./website-sdk-config.json quote --input ./quote-input.json
+```
+
+Output defaults to JSON. Use `--output pretty` for inspected terminal output:
+
+```sh
+website-sdk --backend v10 quote --input ./quote-input.json --output pretty
+```
+
+The CLI only creates the initial quote. Additional service, cancellation policy, and insurance selections are SDK-only operations.
+
+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`.