@v-office/website-sdk 1.2.0 → 2.0.0

package/instructions/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+This file is the versioned changelog index for the website SDK instructions.
+
+## Versions
+
+- `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,9 @@
+# Migration
+
+This file is the versioned migration index for the website SDK instructions.
+
+## Available Guides
+
+- `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,62 @@
+# Website SDK Instructions
+
+These instructions describe `@v-office/website-sdk` 2.0.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.
+- `CHANGELOG.md`: versioned changelog index.
+- `MIGRATION.md`: versioned migration index.
+- `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 2.0.0 flat `WebsiteSDKConfig` shape.

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
+
+`website-sdk` 2.0.0 includes a booking CLI 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,92 @@
+# 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. The current `v10` implementation is a placeholder and resolves without sending a backend request.
+
+## Input
+
+```ts
+type ContactInput = {
+  title: string
+  professionalTitle: string
+  forename: string
+  surname: string
+  address: {
+    streetAndHousenumber: string
+    postalCode: string
+    city: string
+    countryCode: string
+  }
+  email: string
+  phone?: string
+  message: string
+}
+```
+
+`ContactSubmitInput` is the core SDK type name. `ContactInput` remains exported as a legacy alias.
+
+Sample:
+
+```json
+{
+  "title": "Ms",
+  "professionalTitle": "",
+  "forename": "Jane",
+  "surname": "Doe",
+  "address": {
+    "streetAndHousenumber": "Main Street 1",
+    "postalCode": "12345",
+    "city": "Berlin",
+    "countryCode": "DE"
+  },
+  "email": "jane@example.com",
+  "phone": "+49123456789",
+  "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 2.0.0 error shape uses `source` instead of the legacy `backend` field.
+
+## 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`.