@v-office/website-sdk 1.2.1 → 2.1.0

package/instructions/quote.md

@@ -0,0 +1,342 @@
+# 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.
+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
+
+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"
+    },
+    "voucher": {
+      "code": "SUMMER26",
+      "status": "applied",
+      "message": "The voucher code was applied."
+    },
+    "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, 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
+
+Additional services are exposed on an available quote as `quote.additionalServices`.
+
+```json
+{
+  "id": "linen",
+  "label": "Bed linen",
+  "charge": "25.00 EUR",
+  "available": true,
+  "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`. 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
+
+Cancellation policies are exposed on `quote.cancellationPolicies` when the backend offers selectable policies.
+
+```json
+{
+  "id": "alternative",
+  "label": "Flexible cancellation",
+  "selected": false,
+  "available": true,
+  "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`.

package/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`.