@v-office/website-sdk 1.2.1 → 2.1.0

package/dist/translations/shared/de-DE/contact.json

@@ -0,0 +1,19 @@
+{
+  "contact.submit.field.title": "Anrede",
+  "contact.submit.field.professionalTitle": "Titel",
+  "contact.submit.field.forename": "Vorname",
+  "contact.submit.field.surname": "Nachname",
+  "contact.submit.field.address.streetAndHousenumber": "Straße und Hausnummer",
+  "contact.submit.field.address.postalCode": "Postleitzahl",
+  "contact.submit.field.address.city": "Ort",
+  "contact.submit.field.address.countryCode": "Land",
+  "contact.submit.field.email": "E-Mail",
+  "contact.submit.field.phone": "Telefon",
+  "contact.submit.field.subject": "Betreff",
+  "contact.submit.field.message": "Nachricht",
+  "contact.submit.validation.summary": "Bitte prüfen Sie Ihre Kontaktanfrage.",
+  "contact.submit.validation.required": "{field} ist erforderlich.",
+  "contact.submit.validation.invalid_email": "Bitte geben Sie eine gültige E-Mail-Adresse ein.",
+  "contact.submit.validation.invalid_country_code": "Bitte geben Sie ein gültiges Land an.",
+  "contact.submit.validation.tooLong": "{field} darf höchstens {maxLength} Zeichen lang sein."
+}

package/dist/translations/shared/de-DE/quote.json

@@ -4,5 +4,9 @@
   "quote.sections.tax": "Steuern & Abgaben",
   "quote.additionalService.day": " / Tag",
   "quote.additionalService.night": " / Nacht",
-  "quote.status.unavailable.notBookable": "Nicht verfügbar"
+  "quote.status.unavailable.notBookable": "Nicht verfügbar",
+  "quote.optionCombination.unavailable": "Diese Optionskombination ist nicht verfügbar.",
+  "quote.voucher.applied": "Der Rabattcode wurde angewendet.",
+  "quote.voucher.notApplied": "Der Rabattcode konnte nicht angewendet werden.",
+  "quote.voucher.unknown": "Das Backend hat nicht bestätigt, ob der Rabattcode angewendet wurde."
 }

package/dist/translations/shared/en-US/contact.json

@@ -0,0 +1,19 @@
+{
+  "contact.submit.field.title": "Title",
+  "contact.submit.field.professionalTitle": "Professional title",
+  "contact.submit.field.forename": "First name",
+  "contact.submit.field.surname": "Last name",
+  "contact.submit.field.address.streetAndHousenumber": "Street and house number",
+  "contact.submit.field.address.postalCode": "Postal code",
+  "contact.submit.field.address.city": "City",
+  "contact.submit.field.address.countryCode": "Country",
+  "contact.submit.field.email": "Email",
+  "contact.submit.field.phone": "Phone",
+  "contact.submit.field.subject": "Subject",
+  "contact.submit.field.message": "Message",
+  "contact.submit.validation.summary": "Please check your contact request.",
+  "contact.submit.validation.required": "{field} is required.",
+  "contact.submit.validation.invalid_email": "Please enter a valid email address.",
+  "contact.submit.validation.invalid_country_code": "Please enter a valid country.",
+  "contact.submit.validation.tooLong": "{field} must be at most {maxLength} characters long."
+}

package/dist/translations/shared/en-US/quote.json

@@ -4,5 +4,9 @@
   "quote.sections.tax": "Taxes & Fees",
   "quote.additionalService.day": " / day",
   "quote.additionalService.night": " / night",
-  "quote.status.unavailable.notBookable": "Not available"
+  "quote.status.unavailable.notBookable": "Not available",
+  "quote.optionCombination.unavailable": "This option combination is unavailable.",
+  "quote.voucher.applied": "The voucher code was applied.",
+  "quote.voucher.notApplied": "The voucher code could not be applied.",
+  "quote.voucher.unknown": "The backend did not confirm whether the voucher code was applied."
 }

package/dist/translations/v10/de-DE/mapped-search-filters.json

@@ -0,0 +1,3 @@
+{
+  "MappedSearchFilters.pets.label": "Hunde willkommen"
+}

package/dist/translations/v10/en-US/mapped-search-filters.json

@@ -0,0 +1,3 @@
+{
+  "MappedSearchFilters.pets.label": "Dogs welcome"
+}

package/instructions/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+This file is the versioned changelog index for the website SDK instructions.
+
+## Versions
+
+- `versions/2.1.0/CHANGELOG.md`: `@v-office/website-sdk` 2.1.0 release notes.
+- `versions/2.0.0/CHANGELOG.md`: `@v-office/website-sdk` 2.0.0 release notes.
+
+Keep each future release in its own version directory so consumers can see which package version introduced each change.

package/instructions/MIGRATION.md

@@ -0,0 +1,10 @@
+# Migration
+
+This file is the versioned migration index for the website SDK instructions.
+
+## Available Guides
+
+- `versions/2.1.0/MIGRATION.md`: migrate from `@v-office/website-sdk` 2.0.0 to 2.1.0.
+- `versions/2.0.0/MIGRATION.md`: migrate from the legacy 1.x CMS-style website SDK API to `@v-office/website-sdk` 2.0.0.
+
+Keep each future migration in its own version directory so consumers can clearly see the source and target versions for every upgrade path.

package/instructions/README.md

@@ -0,0 +1,64 @@
+# Website SDK Instructions
+
+These instructions describe `@v-office/website-sdk` 2.1.0.
+
+Use this directory as the consumer-facing reference for the package:
+
+- `creation.md`: SDK construction, config, options, and CLI config files.
+- `rentals.md`: `sdk.static.rentals.getRentals`.
+- `filter.md`: `sdk.static.filter.getFilters`.
+- `search.md`: `sdk.live.search.search`.
+- `availability.md`: date-picker availability flows.
+- `quote.md`: quote, additional services, cancellation policy, and insurance flows.
+- `booking.md`: booking and payment option submission.
+- `contact.md`: contact submission.
+- `document-structured-json.md`: `sdk.static.documents.getTermsAndPrivacyPolicy` and structured document JSON rendering rules.
+- `CHANGELOG.md`: versioned changelog index.
+- `MIGRATION.md`: versioned migration index.
+- `versions/2.1.0/`: 2.1.0 release notes and 2.0.0-to-2.1.0 migration guide.
+- `versions/2.0.0/`: release-specific 2.0.0 changelog and 1.x-to-2.0.0 migration guide.
+
+## Package
+
+```sh
+pnpm add @v-office/website-sdk
+```
+
+The package is ESM-only and exports the root SDK facade from `@v-office/website-sdk`.
+
+## Quick Start
+
+```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();
+}
+```
+
+## CLI
+
+```sh
+website-sdk --backend v10 rentals --locale de-DE
+website-sdk --backend v9 filters --locale en-US
+website-sdk --backend v10 search --locale de-DE --query "adults=2"
+```
+
+Config file examples in these docs use the flat `WebsiteSDKConfig` shape introduced in 2.0.0 and kept in 2.1.0.

package/instructions/availability.md

@@ -0,0 +1,157 @@
+# Availability
+
+## Service
+
+Use the live availability API to build date-picker flows:
+
+```ts
+const initial = await sdk.live.availability.getInitialAvailability(input);
+const selected = await sdk.live.availability.getStartDateSelectedAvailability(input);
+```
+
+`getInitialAvailability` marks possible start dates. `getStartDateSelectedAvailability` marks possible end dates after a start date was selected.
+
+## Input
+
+Initial availability:
+
+```ts
+type InitialAvailabilityInput = {
+  locale: "de-DE" | "en-US";
+  rentalId: string;
+  calculateFromDate: string;
+  calculateThroughDate: string;
+};
+```
+
+Start-date-selected availability:
+
+```ts
+type StartDateSelectedAvailabilityInput = InitialAvailabilityInput & {
+  selectedStartDate: string;
+};
+```
+
+Sample:
+
+```json
+{
+  "locale": "de-DE",
+  "rentalId": "123",
+  "calculateFromDate": "2026-07-01",
+  "calculateThroughDate": "2026-08-01"
+}
+```
+
+Dates are local dates formatted as `YYYY-MM-DD`. For `v9`, `rentalId` must be a numeric vOffice unit id.
+
+## Output
+
+Initial availability returns `Promise<InitialAvailabilityOutput>`.
+
+```json
+{
+  "calendarDays": {
+    "2026-07-01": {
+      "canBeStartDate": true,
+      "isAvailableDate": true,
+      "status": "available",
+      "formattedPrice": "120.00 EUR",
+      "tooltip": null
+    },
+    "2026-07-02": {
+      "canBeStartDate": false,
+      "isAvailableDate": false,
+      "status": "check_in_not_allowed",
+      "formattedPrice": null,
+      "tooltip": "Arrival is not possible on this date."
+    }
+  },
+  "minPersons": null,
+  "maxPersons": 6,
+  "maxAdults": 4
+}
+```
+
+Start-date-selected availability returns `Promise<StartDateSelectedAvailabilityOutput>`.
+
+```json
+{
+  "calendarDays": {
+    "2026-07-08": {
+      "canBeEndDate": false,
+      "canBeNewStartDate": false,
+      "status": "same_day",
+      "tooltip": null
+    },
+    "2026-07-15": {
+      "canBeEndDate": true,
+      "canBeNewStartDate": false,
+      "status": "available",
+      "tooltip": null
+    }
+  }
+}
+```
+
+Common statuses include `available`, `before_today`, `check_in_not_allowed`, `no_valid_check_out_from_start`, `after_last_bookable_date`, and `unavailable`. End-date results can also return `same_day`, `not_after_selected_start`, `minimum_stay_not_met`, `check_out_not_allowed`, and range-crossing statuses.
+
+## Configuration
+
+Use flat `WebsiteSDKConfig` files.
+
+`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"
+}
+```
+
+Availability uses localized tooltips from the translation service. `v10` availability queries are rate-limited to one backend request per second, queued up to five requests, and cached per rental for 30 seconds.
+
+## CLI Usage
+
+Fetch initial availability:
+
+```sh
+website-sdk --backend v10 availability initial --rental-id 123 --calculate-from-date 2026-07-01 --calculate-through-date 2026-08-01
+```
+
+Fetch availability after selecting a start date:
+
+```sh
+website-sdk --backend v9 availability start-date-selected --rental-id 123 --selected-start-date 2026-07-08 --calculate-from-date 2026-07-01 --calculate-through-date 2026-08-01
+```
+
+Use files instead of environment variables:
+
+```sh
+website-sdk --backend v10 --config ./website-sdk-config.json availability initial --rental-id 123 --calculate-from-date 2026-07-01 --calculate-through-date 2026-08-01
+```
+
+Output defaults to JSON. Use `--output pretty` for inspected terminal output:
+
+```sh
+website-sdk --backend v10 availability initial --rental-id 123 --calculate-from-date 2026-07-01 --calculate-through-date 2026-08-01 --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/booking.md

@@ -0,0 +1,165 @@
+# Booking
+
+## Service
+
+Use the live booking API to turn an available `GuestQuote` into a booking:
+
+```ts
+const booking = await sdk.live.booking.book(input);
+```
+
+The `quote` must be the `GuestQuote` instance returned by `sdk.live.quote.quote(...)`, optionally updated through quote selection helpers.
+
+## Input
+
+```ts
+type BookingInput = {
+  quote: GuestQuote;
+  contact: {
+    forename: string;
+    surname: string;
+    title?: string;
+    birthdate?: string;
+    address: {
+      street: string;
+      housenumber?: string;
+      postalcode: string;
+      city: string;
+      countryCode: string;
+    };
+    contactDetails: { email: string; phone: string } | { email: string } | { phone: string };
+    note?: string;
+  };
+  relativeRedirectUrl: string;
+};
+```
+
+Sample:
+
+```ts
+const quoteResult = await sdk.live.quote.quote(quoteInput);
+if (quoteResult.status !== "available") throw new Error(quoteResult.reason);
+
+const booking = await sdk.live.booking.book({
+  quote: quoteResult.quote,
+  contact: {
+    forename: "Jane",
+    surname: "Doe",
+    title: "Ms",
+    address: {
+      street: "Main Street",
+      housenumber: "1",
+      postalcode: "12345",
+      city: "Berlin",
+      countryCode: "DE",
+    },
+    contactDetails: {
+      email: "jane@example.com",
+      phone: "+49123456789",
+    },
+    note: "Please prepare a baby bed.",
+  },
+  relativeRedirectUrl: "/booking/payment-return",
+});
+```
+
+`relativeRedirectUrl` is used for online payment redirects after booking creation.
+
+## Output
+
+Returns `Promise<BookingOutput>`.
+
+Sample:
+
+```json
+{
+  "bookingNumber": "B-2026-0001",
+  "guestToken": "guest-token",
+  "paymentSchedules": [
+    {
+      "label": "Deposit",
+      "dueOn": "2026-06-15",
+      "lines": [
+        {
+          "label": "Deposit",
+          "amount": "300.00 EUR"
+        }
+      ],
+      "total": "300.00 EUR",
+      "paymentOptions": [
+        {
+          "kind": "bank_transfer",
+          "label": "Bank transfer",
+          "holder": "Example GmbH",
+          "iban": "DE02120300000000202051",
+          "swiftOrBic": "BYLADEM1001",
+          "remittanceText": "B-2026-0001"
+        },
+        {
+          "kind": "redirect",
+          "provider": "adyen",
+          "label": "Credit card",
+          "url": "https://checkout.example.com"
+        }
+      ]
+    }
+  ],
+  "insurancePaymentOptions": []
+}
+```
+
+Payment option variants:
+
+- `bank_transfer`: display-only payment details.
+- `redirect`: redirect the browser to the payment URL.
+- `form_post`: submit a generated HTML form, currently used for PayPal-style flows.
+- `stripe_checkout`: redirect to Stripe Checkout when a `url` is present.
+
+Use `sdk.live.booking.submitPaymentOption(option)` or the top-level `submitPaymentOption(option)` export for non-bank-transfer payment options in a browser environment.
+
+## Configuration
+
+Booking requests are rate-limited to one backend request per second with a queue size of five. `v9` books through the v0 `book` action and can initialize Stripe payment data. `v10` books through GraphQL and initializes Adyen redirect payment options.
+
+## CLI Usage
+
+The CLI includes a booking command. It creates a fresh quote from a quote input file, then books that quote with a booking contact file:
+
+```sh
+website-sdk --backend v10 booking book --quote-input ./quote-input.json --contact-input ./booking-contact.json --relative-redirect-url /booking/payment-return --yes
+```
+
+The command requires `--yes` because it creates a booking in the configured backend.
+
+Example `booking-contact.json`:
+
+```json
+{
+  "forename": "Jane",
+  "surname": "Doe",
+  "title": "Ms",
+  "address": {
+    "street": "Main Street",
+    "housenumber": "1",
+    "postalcode": "12345",
+    "city": "Berlin",
+    "countryCode": "DE"
+  },
+  "contactDetails": {
+    "email": "jane@example.com",
+    "phone": "+49123456789"
+  },
+  "note": "Please prepare a baby bed."
+}
+```
+
+Use files instead of environment variables:
+
+```sh
+website-sdk --backend v10 --config ./website-sdk-config.json booking book --quote-input ./quote-input.json --contact-input ./booking-contact.json --relative-redirect-url /booking/payment-return --yes
+```
+
+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/contact.md

@@ -0,0 +1,110 @@
+# Contact
+
+## Service
+
+Use the live contact API to submit a contact request:
+
+```ts
+await sdk.live.contact.submit(input);
+```
+
+`v9` submits the request through the v0 `saveMessage` action. `v10` submits the request through the `messengeremail_newContactRequest` GraphQL operation.
+
+## Input
+
+```ts
+type ContactInput = {
+  locale?: "de-DE" | "en-US";
+  title: string;
+  professionalTitle: string;
+  forename: string;
+  surname: string;
+  address: {
+    streetAndHousenumber: string;
+    postalCode: string;
+    city: string;
+    countryCode: string;
+  };
+  email: string;
+  phone: string;
+  subject: string;
+  message: string;
+};
+```
+
+`ContactSubmitInput` is the core SDK type name. `ContactInput` remains exported as a legacy alias.
+
+Sample:
+
+```json
+{
+  "locale": "de-DE",
+  "title": "Ms",
+  "professionalTitle": "",
+  "forename": "Jane",
+  "surname": "Doe",
+  "address": {
+    "streetAndHousenumber": "Main Street 1",
+    "postalCode": "12345",
+    "city": "Berlin",
+    "countryCode": "DE"
+  },
+  "email": "jane@example.com",
+  "phone": "+49123456789",
+  "subject": "Question about a rental",
+  "message": "I have a question about a rental."
+}
+```
+
+## Output
+
+Returns `Promise<ContactSubmitOutput>`. `ContactSubmitOutput` is currently `void`.
+
+Successful CLI output:
+
+```json
+{
+  "ok": true
+}
+```
+
+Errors are reported as `CoreSDKError`, also exported as the compatibility alias `CMSError`. The current error shape uses `source` instead of the legacy `backend` field.
+
+Contact input is validated before submitting to either backend. Validation failures reject with a `CoreSDKError` using `operation: "contact.submit.validation"`. The error `message` is translated with `input.locale` and defaults to German (`de-DE`) when no locale is provided. Field-level details are available on `error.cause.issues`:
+
+```json
+{
+  "issues": [
+    {
+      "path": "email",
+      "code": "invalid_email",
+      "message": "Bitte geben Sie eine gültige E-Mail-Adresse ein."
+    }
+  ]
+}
+```
+
+## Configuration
+
+Contact requests are rate-limited to one request per second with a queue size of five.
+
+## CLI Usage
+
+Create `contact-input.json` with a `ContactSubmitInput` object, then submit with explicit confirmation:
+
+```sh
+website-sdk --backend v9 contact submit --input ./contact-input.json --yes
+```
+
+Use files instead of environment variables:
+
+```sh
+website-sdk --backend v9 --config ./website-sdk-config.json contact submit --input ./contact-input.json --yes
+```
+
+Without `--yes`, the command fails before submitting because contact requests send data to the configured backend.
+
+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`.