@v-office/website-sdk 1.2.1 → 2.0.0

package/README.md

@@ -1,269 +1,128 @@
-# tsdown-starter
+# @v-office/website-sdk
 
-A starter for creating a TypeScript package.
+Website-facing SDK facade for vOffice backends.
 
-## Development
+Version 2.0.0 is the replacement line for the legacy website SDK implementation. It keeps the high-level SDK method tree stable while moving shared domain contracts and v10 runtime behavior into `@v-office/sdk-core`.
 
-- Install dependencies:
+## Install
 
-```bash
-pnpm install
+```sh
+pnpm add @v-office/website-sdk
 ```
 
-- Run the unit tests:
+The package is ESM-only and exposes:
 
-```bash
-pnpm run test
-```
-
-- Build the library:
-
-```bash
-pnpm run build
-```
-
-- Playground
-
-```bash
-pnpm run playground
-```
-
-## CLI
+- `@v-office/website-sdk`
+- `@v-office/website-sdk/cli`
+- `@v-office/website-sdk/package.json`
 
-The CLI exposes common SDK operations without editing `playground.ts` for each
-manual test. In local development, use `pnpm cli -- ...`; when installed as a
-package binary, use `cms-sdk ...`.
+## Create a SDK
 
-The CLI reads the same environment variables as `playground.ts`. For v9:
-
-```bash
-HUB_GRAPHQL_URL
-HUB_V1_API_BASE_URL
-HUB_V0_API_BASE_URL
-HUB_API_KEY
-IMAGE_PROXY_BASE_URL
-```
-
-For v10:
-
-```bash
-VOFFICE_API_ENDPOINT
-VOFFICE_LOCAL_DEV_ACCESS_TOKEN
-VOFFICE_IMAGE_BASE_URL
-```
-
-You can inspect the required environment variables and resolved config:
-
-```bash
-pnpm cli --backend v9 config env
-pnpm cli --backend v10 config show --output pretty
-```
+```ts
+import { createWebsiteSDK, defineWebsiteSDKOptions } from '@v-office/website-sdk'
 
-You can also pass a complete parsed config or shared SDK options file:
-
-```bash
-pnpm cli --backend v9 --config ./cms-config.v9.json config show
-pnpm cli --backend v10 --options ./cms-options.json filters --locale de-DE
-```
-
-### Static Services
-
-Fetch rentals:
-
-```bash
-pnpm cli --backend v9 rentals --locale de-DE
-pnpm cli --backend v10 rentals --locale de-DE
-```
-
-Fetch filters:
-
-```bash
-pnpm cli --backend v9 filters --locale de-DE
-pnpm cli --backend v10 filters --locale de-DE
-```
-
-### Search Service
-
-Run the same query shape used in `playground.ts`:
-
-```bash
-pnpm cli --backend v9 search \
-  --locale de-DE \
-  --limit 2 \
-  --query "start=20-06-2026&end=27-06-2026&adults=2&childrenAges=5%2C13&babies=1&pets=1&wifi&bedrooms=6&bbq=true&youthgroups=on_request&beachdistance=200&scope=entire_home%2Cprivate_room&reet&complexFilter"
-```
-
-Use the returned `pageInfo.nextCursor` for the next page:
-
-```bash
-pnpm cli --backend v10 search \
-  --locale de-DE \
-  --limit 2 \
-  --cursor "<nextCursor>" \
-  --query "start=20-06-2026&end=27-06-2026&adults=2&childrenAges=5%2C13&babies=1&pets=1"
-```
-
-### Availability Service
-
-Fetch the initial availability calendar:
-
-```bash
-pnpm cli --backend v9 availability initial \
-  --locale de-DE \
-  --rental-id 134990 \
-  --calculate-from-date 2026-05-01 \
-  --calculate-through-date 2026-08-31
-```
-
-Fetch availability after selecting a start date:
-
-```bash
-pnpm cli --backend v9 availability start-date-selected \
-  --locale de-DE \
-  --rental-id 134990 \
-  --selected-start-date 2026-06-17 \
-  --calculate-from-date 2026-05-01 \
-  --calculate-through-date 2026-08-31
-```
-
-The v10 playground rental can be used in the same commands:
-
-```bash
-pnpm cli --backend v10 availability initial \
-  --locale de-DE \
-  --rental-id GMB2KczZnEXkdcF2LscQFX \
-  --calculate-from-date 2026-07-08 \
-  --calculate-through-date 2026-07-11
-```
-
-### Quote Service
-
-Create a JSON fixture for a quote input, for example:
-
-```json
-{
-  "locale": "de-DE",
-  "rentalId": "159521",
-  "period": {
-    "start": "2026-07-08",
-    "end": "2026-07-11"
-  },
-  "occupancy": {
-    "adults": 1,
-    "children": 0,
-    "babies": 0,
-    "pets": 0
+const sdk = createWebsiteSDK({
+  config: {
+    backend: 'v10',
+    apiEndpoint: 'https://api.example.com/graphql',
+    accessToken: '...',
+    imageBaseUrl: 'https://images.example.com',
   },
-  "destinationCountryCode": "DE"
+  options: defineWebsiteSDKOptions({
+    rentalScope: {
+      propertyId: 'property-1',
+    },
+  }),
+})
+
+try {
+  const rentals = await sdk.static.rentals.getRentals({ locale: 'de-DE' })
+  console.log(rentals)
+} finally {
+  await sdk.dispose()
 }
 ```
 
-Then run:
-
-```bash
-pnpm cli --backend v9 quote --input ./quote-input.v9.json
-```
-
-For the v10 playground rental with the voucher:
+For v9:
 
-```json
-{
-  "locale": "de-DE",
-  "rentalId": "GMB2KczZnEXkdcF2LscQFX",
-  "period": {
-    "start": "2026-07-08",
-    "end": "2026-07-11"
-  },
-  "occupancy": {
-    "adults": 1,
-    "children": 0,
-    "babies": 0,
-    "pets": 0
+```ts
+const sdk = createWebsiteSDK({
+  config: {
+    backend: 'v9',
+    graphqlUrl: 'https://example.com/graphql',
+    apiKey: '...',
+    imageProxyBaseUrl: 'https://images.example.com',
+    v1ApiBaseUrl: 'https://example.com/api/v1',
+    v0ApiBaseUrl: 'https://example.com/api/v0',
   },
-  "destinationCountryCode": "DE",
-  "voucher": "OFFER11"
-}
-```
-
-```bash
-pnpm cli --backend v10 quote --input ./quote-input.v10.json
+})
 ```
 
-### Contact Service
+## SDK Surface
 
-Contact submission is guarded by `--yes` because it sends data to the backend.
-Create a JSON fixture like the playground input:
+The facade exposes Promise-based static and live APIs:
 
-```json
-{
-  "title": "Herr",
-  "professionalTitle": "Dr.",
-  "forename": "Max",
-  "surname": "Mustermann",
-  "address": {
-    "streetAndHousenumber": "Musterstraße 42",
-    "postalCode": "11111",
-    "city": "Musterstadt",
-    "countryCode": "DE"
-  },
-  "email": "max.mustermann@muster.de",
-  "phone": "+49123456789",
-  "message": "Muster-Hinweis\nMuster"
-}
-```
+```ts
+sdk.static.rentals.getRentals(input)
+sdk.static.filter.getFilters(input)
 
-Then submit it explicitly:
+sdk.live.search.search(input)
+sdk.live.availability.getInitialAvailability(input)
+sdk.live.availability.getStartDateSelectedAvailability(input)
+sdk.live.quote.quote(input)
+sdk.live.booking.book(input)
+sdk.live.contact.submit(input)
 
-```bash
-pnpm cli --backend v9 contact submit --input ./contact-input.json --yes
+await sdk.dispose()
 ```
 
-### Booking Service
+Quote mutation helpers are available under `sdk.live.quote`:
 
-Booking and quote-selection flows still need code for now because they operate
-on a live `GuestQuote` class instance returned by the quote service. Keep using
-`playground.ts` for booking, additional service selection, cancellation policy
-selection, insurance selection, insurance pre-contracts, insurance payment
-selection, and insurance booking until those flows have a stable JSON
-serialization contract.
+- `addAdditionalService`
+- `removeAdditionalService`
+- `clearAdditionalServices`
+- `selectCancellationPolicy`
+- `selectInsurance`
+- `createInsurancePreContract`
+- `selectInsurancePayment`
+- `bookInsurance`
 
-## TODO
-
-### My-Stuff
-
-- Payment (needs to be tested)
-
-- Zahlung vor Ort (v9)
-
-- Insurances
-
-- Contact-Form (v10 -> Ticket)
-- Contact-Form (v9 -> sendMessage)
+## CLI
 
-- Auto-Regions (v10)
+```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"
+```
 
-### Waiting
+The CLI can read config from environment variables or from JSON files:
 
-## v9
+```sh
+website-sdk --backend v10 --config ./website-sdk-config.json --options ./website-sdk-options.json rentals --locale de-DE
+```
 
-- Alternatives
-- Filter für getRentals
-- Always applied Filter für search
+For v10, environment configuration uses:
 
-### Custom Attributes
+- `VOFFICE_API_ENDPOINT`
+- `VOFFICE_LOCAL_DEV_ACCESS_TOKEN`
+- `VOFFICE_IMAGE_BASE_URL`
 
-- Suche mit Filter nach Custom-Attribute (boolean)
-  - v10 nicht implementiert - wird bald
-  - v9 müsste über Hub Filter-Schema gemacht werden
-  - unified surface
+For v9, environment configuration uses:
 
-### Optional
+- `HUB_GRAPHQL_URL`
+- `HUB_V1_API_BASE_URL`
+- `HUB_API_KEY`
+- `IMAGE_PROXY_BASE_URL`
+- `HUB_V0_API_BASE_URL` optional
 
-#### Filter-Counts
+## Migration From Legacy
 
-- In v10 müsste man ganze Suche triggern - nicht gut
-- In v9 müsste über Hub Filter-Schema gemacht werden
+This is a breaking release for consumers migrating from the legacy SDK API. The largest changes are:
 
-### getRentals
+- `createCMSSDKFromParsedConfig(...)` was replaced by `createWebsiteSDK({ config, options })`.
+- Config moved from nested `{ backend, v9: {...} }` / `{ backend, v10: {...} }` objects to flat `WebsiteSDKConfig` objects.
+- Public type names moved from CMS naming to Website naming.
+- The error model now comes from `@v-office/sdk-core`.
+- CLI config JSON uses the new flat config shape.
 
-- highlightsPrioritization does not correctly work with e.g. maxPersons
+See `instructions/` for the full consumer documentation. Version-specific release notes and migration details live under `instructions/versions/2.0.0/`, with indexes at `instructions/CHANGELOG.md` and `instructions/MIGRATION.md`.