@v-office/website-sdk 2.5.1 → 2.8.0

package/instructions/rentals.md

@@ -147,14 +147,38 @@ Optional `WebsiteSDKOptions`:
 
 ```json
 {
-  "rentalHighlightPrioritization": ["bedrooms", "bathrooms", "maxPersons", "wifi"],
+  "customAttributes": {
+    "catalog": {
+      "privateSauna": {
+        "id": "GQYKYgMVh28X7VLGursbkt",
+        "type": "BOOLEAN"
+      }
+    },
+    "select": {
+      "privateSauna": {
+        "label": { "de-DE": "Sauna", "en-US": "Sauna" }
+      }
+    }
+  },
+  "rentalHighlightPrioritization": ["bedrooms", "privateSauna", "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.
+`rentalHighlightPrioritization` controls the order of rental `highlights`. `rentalPropertyHighlightPrioritization` controls property highlights for v10 property data. Translation overrides affect localized labels.
+
+In CLI JSON, `customAttributes` contains catalog and selection inputs; the CLI builds
+the validated registry. Typed applications normally call `defineCustomAttributes`
+and pass its result instead.
+
+Custom attributes configured through `customAttributes` add values to rental output on
+both backends. A value appears in `highlights` only when its key is listed in
+`rentalHighlightPrioritization`, and in `attributes` under the group named by its
+authored `category` — alongside built-in attributes of that category, not in a separate
+bucket. Category and attribute `label`s in the output are localized strings, never
+stable keys. See `custom-attributes.md`.
 
 ## CLI Usage
 

package/instructions/search.md

@@ -272,7 +272,12 @@ Sample:
   "appliedFilters": [
     {
       "key": "wifi",
-      "label": "WiFi"
+      "label": "WLAN"
+    },
+    {
+      "key": "region",
+      "label": "Region: Norden",
+      "value": "north"
     }
   ],
   "unusedFilterKeys": [],
@@ -285,13 +290,34 @@ Sample:
 
 Search items share the rental base fields and may include `scope`, `address`, `property`, `highlights`, and `formattedTotal`. Exact-period results are returned in `items`; alternative-period suggestions are returned in root-level `alternatives`.
 
+`appliedFilters` reports what the backend actually applied, and is what a "remove
+this filter" chip should be built from. `label` is localized presentation and can
+repeat, so it cannot identify a filter; `key` plus `value` can. `value` is the
+canonical applied value and is present only for filters that carry one — on/off
+filters are identified by `key` alone. A key you sent that is **not** listed here
+appears in `unusedFilterKeys` and had no effect on the result set. A scalar key may
+appear in both arrays when its first value was applied but additional values were
+rejected.
+
+Composition filters are atomic in both metadata and the backend payload. The SDK
+validates all configured leaves against the active backend before committing any
+generated GraphQL or REST input. If one leaf is unsupported or malformed, no
+composition-generated leaf restricts the result, and only the composition key is
+reported unused. Direct filters are tracked independently and remain applied even
+when a failed composition references the same key.
+
+When every leaf succeeds, `appliedFilters` contains both the composition entry and
+the expanded leaf entries. A UI may collapse those leaves under the composition for
+display, but should keep the returned keys and canonical values when removing direct
+filters.
+
 ## v10 Backend
 
 v10 search runs against the dedicated REST search backend (`POST` to the configured `searchEndpoint`). Existing calls and the output type remain compatible, while the input additionally supports optional sorting. v10 results reflect the REST projection:
 
 - At most five images per item, and no image `category`.
 - `property` is the minimal `{ id, nameOrLabel }` shape. Hydrate `property.location`, `property.images`, or `property.address` from `sdk.static.rentals.getRentals(...)` when a card needs them.
-- Custom-attribute search filters and highlights require a `customAttributeDefinitionManifest`; without it, custom-attribute query keys are left in `unusedFilterKeys` and no custom-attribute highlights are added.
+- Custom-attribute search filters and highlights require the `customAttributes` registry. A definition with no catalog ID cannot be executed, so its query key is left in `unusedFilterKeys`. v9 never executes a custom-attribute filter at all. See `custom-attributes.md`.
 - Fixed-period and flexible searches are priced by the REST backend and require occupancy.
 - Pagination uses the backend `from`/`size` window behind the same opaque `cursor`, capped at 1,000 results.
 
@@ -299,7 +325,7 @@ v10 search runs against the dedicated REST search backend (`POST` to the configu
 
 Use flat `WebsiteSDKConfig` files and optional `WebsiteSDKOptions`.
 
-For v10, config requires `searchEndpoint` (the full REST search URL) as of 2.5.0. See `creation.md` for `searchEndpoint` and the `customAttributeDefinitionManifest` option.
+For v10, config requires `searchEndpoint` (the full REST search URL) as of 2.5.0. See `creation.md` for `searchEndpoint` and the `customAttributes` option.
 
 Custom filter definitions can extend accepted search query keys. Search requests are rate-limited to one backend request per second with a queue size of five.
 

package/instructions/versions/2.5.0/MIGRATION.md

@@ -1,5 +1,10 @@
 # Migration: 2.4.3 to 2.5.0
 
+> Custom-attribute manifest guidance below is historically correct for 2.5.x but is
+> superseded in 2.8.0. When upgrading current packages, follow
+> `../2.8.0/MIGRATION.md` to replace `customAttributeDefinitionManifest` with
+> `defineCustomAttributes`.
+
 This guide covers upgrading `@v-office/website-sdk` from 2.4.3 to 2.5.0.
 
 2.5.0 keeps `createWebsiteSDK({ config, options })`, the flat `WebsiteSDKConfig`, and existing SDK calls. v10 search now runs against the dedicated REST search backend, which requires one new config field and, for custom-attribute search, one new option. Search input also gains optional sorting, and static v10 rental loading uses the full Rental APIs internally. Existing calls and output types remain compatible.

package/instructions/versions/2.6.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog: 2.6.0
+
+`@v-office/website-sdk` 2.6.0 was never published. The Stripe Checkout work
+documented under this version during development shipped as 2.7.0 on 2026-07-27.
+
+Use `../2.7.0/CHANGELOG.md` as the authoritative release record.

package/instructions/versions/2.6.0/MIGRATION.md

@@ -0,0 +1,6 @@
+# Migration: 2.6.0
+
+`@v-office/website-sdk` 2.6.0 was never published. The planned Stripe Checkout
+change shipped in 2.7.0.
+
+Consumers upgrading from 2.5.x should follow `../2.7.0/MIGRATION.md`.

package/instructions/versions/2.7.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog: 2.7.0
+
+Release date: 2026-07-27
+
+This release makes v9 `stripe_checkout` payment options submittable. The vOffice
+`initStripePayment` action returns only session metadata, so `submitPaymentOption`
+now opens the Checkout Session with Stripe.js when the backend omits the session
+URL. Config, service calls, and output types are unchanged.
+
+## Added
+
+- `submitPaymentOption` and `submitPaymentOptionEffect` now complete
+  `stripe_checkout` options that carry only `sessionId` and `accountId`.
+- Stripe.js is loaded from `https://js.stripe.com/v3/` on first use and reused for
+  later submissions. Failed loads are not cached, and an existing `window.Stripe`
+  is reused.
+- The SDK includes the vOffice Stripe platform publishable keys, so Stripe Checkout
+  needs no consumer key configuration.
+
+## Changed
+
+- `stripe_checkout` prefers a Checkout Session `url` and falls back to Stripe.js
+  only when the URL is absent.
+- Test (`cs_test_`) and live (`cs_live_`) sessions select the corresponding
+  publishable key automatically.
+- Connected-account sessions pass `accountId` to Stripe.js as `stripeAccount`.
+- Missing-session failures now name both the absent URL and session ID.
+
+## Migration Impact
+
+- Sites that hid Stripe options because `url` was absent can render them again.
+  Gate the button on the payment option being present rather than on `option.url`.
+- Content-Security-Policy must allow `script-src https://js.stripe.com` and
+  `frame-src https://js.stripe.com https://hooks.stripe.com`.
+- Payment submission remains browser-only. A Stripe script or redirect failure is
+  a payment failure after the booking exists, not a booking failure.
+- No config, service-call, or output migration is required. See
+  `versions/2.7.0/MIGRATION.md`.
+
+## Versioning Note
+
+The implementation was documented during development under a planned 2.6.0
+directory, but 2.6.0 was never published. The package was released as 2.7.0; this
+directory is the authoritative release record.

package/instructions/versions/2.7.0/MIGRATION.md

@@ -0,0 +1,79 @@
+# Migration: 2.5.x to 2.7.0
+
+This guide covers upgrading `@v-office/website-sdk` from 2.5.0 or 2.5.1 to 2.7.0.
+Version 2.6.0 was not published.
+
+2.7.0 changes no config, service call, or output type. The runtime change is that
+v9 `stripe_checkout` payment options can now be submitted. Sites without Stripe
+need no migration work.
+
+## Remove Stripe Workarounds
+
+vOffice's `initStripePayment` action can return `sessionId` and `accountId` without
+the Checkout Session URL. The SDK now keeps URL redirects as the preferred path and
+uses Stripe.js when only session metadata is available.
+
+Sites that hid Stripe options without a URL should render them:
+
+```ts
+// Before
+const payable = option.kind !== "stripe_checkout" || option.url !== undefined;
+
+// 2.7.0
+const payable = true;
+```
+
+Delete site-level Stripe.js bridges and publishable-key configuration added only to
+work around the missing URL. The SDK selects the vOffice platform test or live key
+from the session ID and passes connected-account context automatically.
+
+## Content-Security-Policy
+
+If the site sets a CSP, allow:
+
+```text
+script-src https://js.stripe.com
+frame-src https://js.stripe.com https://hooks.stripe.com
+```
+
+Without these directives, Stripe submission fails. Other payment kinds are
+unaffected.
+
+## Error Handling
+
+Stripe.js loading or redirecting can fail. These failures surface as
+`CoreSDKError` with `operation: "paymentSubmission"`. A failed script load is not
+cached, so retrying can succeed.
+
+The booking already exists when payment options are rendered. Present a submission
+failure as a payment problem with the booking number, never as a failed booking:
+
+```ts
+try {
+  await sdk.live.booking.submitPaymentOption(option);
+} catch (error) {
+  showPaymentFailure({ bookingNumber: booking.bookingNumber, error });
+}
+```
+
+Submission remains browser-only.
+
+## Payment Return
+
+The SDK derives Stripe success and cancel URLs from the `relativeRedirectUrl`
+passed to `sdk.live.booking.book(...)`, appending
+`payment=stripe&success=true` or `payment=stripe&cancel=true`. Persist anything the
+return page needs before submitting the payment option because the redirect URL is
+configured before the booking number exists.
+
+A `success=true` return means the browser returned from Stripe, not that payment
+settled. Stripe's webhook confirms payment to vOffice.
+
+## Recommended Steps
+
+1. Upgrade to `@v-office/website-sdk` 2.7.0.
+2. Remove checks that hide Stripe options when `option.url` is missing.
+3. Remove any site-owned Stripe.js bridge and publishable key used for this flow.
+4. Add the Stripe CSP directives when applicable.
+5. Present submission failures as post-booking payment failures.
+6. Smoke-test test-mode and live-mode tenants, including success and cancel returns.

package/instructions/versions/2.8.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog: 2.8.0
+
+This release replaces the loose custom-attribute manifest/configuration split with a
+validated catalog-backed registry shared by rental display, highlights, filter
+discovery, and search.
+
+## Added
+
+- `fetchCustomAttributeCatalog({ config })` reads public v10 custom-attribute
+  definition IDs, keys, types, and option identities at build time.
+- `defineCustomAttributes(...)` joins that catalog with authored labels, exposure,
+  display, category, v9 bindings, and option labels.
+- `defineCustomAttributesFromUnknown(...)`, `parseCustomAttributeCatalog`, and
+  `CustomAttributeCatalogSchema` support CLI/JSON and other untyped inputs.
+- The website package exports the catalog, selection, registry, resolved-attribute,
+  category, and override types needed to author typed configuration.
+- v10 reads public custom-attribute values for rentals and search output. v9 can
+  render the same registry through explicit `p_*` rental-data bindings and `v9Only`
+  entries.
+- Applied value-bearing filters include a canonical `value`, allowing consumers to
+  remove one exact filter value without relying on a localized label.
+
+## Changed
+
+- `WebsiteSDKOptions.customAttributes` now receives the validated registry returned
+  by `defineCustomAttributes`.
+- `customAttributeFilterDefinitions` now contains only `backendFilter` and
+  `composition` definitions. Catalog-backed custom attributes get their filter
+  policy from the registry selection.
+- v10 custom-attribute filters are advertised only when filtering is enabled and a
+  backend definition ID exists. v9 does not advertise or execute catalog custom
+  attributes.
+- Public/internal filter exposure and display are independent. Internal filters are
+  queryable and usable by compositions but absent from `getFilters`.
+- Custom-attribute categories, backend-filter categories, and composition
+  categories are returned as localized display labels. Configuration continues to
+  store stable category keys.
+- Composition discovery is backend-aware. Every configured leaf and value must be
+  executable on the active backend.
+- Composition execution is atomic at the GraphQL/REST payload level. A failed
+  composition contributes no generated leaf and reports only its parent key unused.
+- Nested compositions are rejected while recursive expansion remains unsupported.
+- Query-key ownership is validated against period, occupancy, active-backend
+  built-ins, overlapping custom definitions, and repeated configured filter keys.
+- Rental highlight prioritization remains an explicit ordered list. Custom
+  attributes render only when their resolved key is listed; registry contents do
+  not reorder built-in highlights.
+
+## Removed
+
+- `customAttributeDefinitionManifest`,
+  `CustomAttributeDefinitionManifest`,
+  `CustomAttributeDefinitionManifestEntry`, and related manifest helpers.
+- `source: "customAttribute"` entries in `customAttributeFilterDefinitions`.
+- Unsupported composition expression forms `any`, `gte`, and `lte`.
+- `renderCustomAttributeHighlight`; use registry-backed rental/search output, or
+  `renderResolvedCustomAttribute` from `@v-office/sdk-core`.
+
+## Migration Impact
+
+This is a configuration and public-type migration for consumers using custom
+attributes. Consumers that do not configure custom attributes keep the same SDK
+construction and service calls. Follow `versions/2.8.0/MIGRATION.md`.

package/instructions/versions/2.8.0/MIGRATION.md

@@ -0,0 +1,252 @@
+# Migration: 2.7.0 to 2.8.0
+
+2.8.0 replaces `customAttributeDefinitionManifest` and
+`source: "customAttribute"` filter definitions with one validated custom-attribute
+registry. SDK construction and service method names are unchanged.
+
+Consumers without custom attributes can upgrade without configuration changes.
+
+## 1. Replace the Definition Manifest
+
+Before:
+
+```ts
+const options = defineWebsiteSDKOptions({
+  customAttributeDefinitionManifest: {
+    byKey: {
+      region: {
+        id: "GQYKYgMVh28X7VLGursbkt",
+        key: "region",
+        type: "OPTION",
+        visibility: "PUBLIC",
+      },
+    },
+    byId: {
+      GQYKYgMVh28X7VLGursbkt: {
+        id: "GQYKYgMVh28X7VLGursbkt",
+        key: "region",
+        type: "OPTION",
+        visibility: "PUBLIC",
+      },
+    },
+  },
+});
+```
+
+After:
+
+```ts
+import {
+  defineCustomAttributes,
+  defineWebsiteSDKOptions,
+  fetchCustomAttributeCatalog,
+} from "@v-office/website-sdk";
+
+const catalog = await fetchCustomAttributeCatalog({ config: v10Config });
+
+const customAttributes = defineCustomAttributes({
+  catalog,
+  select: {
+    region: {
+      label: { "de-DE": "Region", "en-US": "Region" },
+      category: "OTHER",
+      filter: true,
+      optionLabels: {
+        north: { "de-DE": "Norden", "en-US": "North" },
+        south: { "de-DE": "Süden", "en-US": "South" },
+      },
+    },
+  },
+});
+
+const options = defineWebsiteSDKOptions({ customAttributes });
+```
+
+`fetchCustomAttributeCatalog` is v10-only, requires a token authorized for the
+public-definition operation, and returns no localized labels. Fetch it in an
+authorized build environment or pin an equivalent literal catalog.
+`defineCustomAttributes` validates the complete catalog/selection join and reports
+all configuration errors together.
+
+## 2. Move Custom-Attribute Filter Policy
+
+Remove every `source: "customAttribute"` entry from
+`customAttributeFilterDefinitions`. Put its behavior in the matching `select`
+entry:
+
+```ts
+select: {
+  occupancyScore: {
+    label: { "de-DE": "Belegung", "en-US": "Occupancy" },
+    category: "ESSENTIALS",
+    filter: {
+      exposure: "public",
+      numericBounds: { min: 1, max: 12 },
+    },
+  },
+}
+```
+
+Use `filter: "internal"` or `filter: { exposure: "internal" }` for a queryable filter
+that must not appear in `getFilters`. Omit `filter` for display only.
+
+`customAttributeFilterDefinitions` remains the home of:
+
+- `backendFilter`: v9 backend-native filters;
+- `composition`: virtual Boolean filters composed from executable leaves.
+
+## 3. Configure Display and v9 Bindings
+
+Display is independent of filter exposure and defaults to `true`. A selected
+catalog attribute can add a v9 rental-data binding:
+
+```ts
+select: {
+  privateSauna: {
+    label: { "de-DE": "Sauna", "en-US": "Sauna" },
+    display: true,
+    filter: true,
+    v9: "p_14418",
+  },
+}
+```
+
+Use `v9Only` for attributes that have no v10 catalog definition:
+
+```ts
+v9Only: {
+  thatchedRoof: {
+    v9: "p_14420",
+    type: "boolean",
+    label: { "de-DE": "Reetdach", "en-US": "Thatched roof" },
+  },
+}
+```
+
+v9 renders bound values but does not advertise or execute catalog custom-attribute
+filters. v10 filtering requires an enabled filter and a catalog ID.
+
+## 4. Update Composition Expressions
+
+Expressions now support equality leaves joined by `all`:
+
+```ts
+expression: {
+  all: [
+    { filter: "privateSauna", value: true },
+    { filter: "maxPersons", value: 4 },
+  ],
+}
+```
+
+Remove `operator`, `gte`, `lte`, and `any`; they never had correct runtime
+semantics. Nested composition references are rejected.
+
+A composition is advertised only if every leaf can execute on the active backend.
+Execution is atomic: if one configured leaf is unknown, unsupported, malformed, or
+conflicts with a direct value, no generated composition leaf enters the backend
+payload and only the composition key is unused.
+
+Successful compositions return the parent and expanded leaves in `appliedFilters`.
+
+## 5. Rename Colliding Query Keys
+
+Every query key must have one owner. Configuration rejects:
+
+- period/occupancy keys such as `start`, `adults`, and `pets`;
+- filterable custom attributes or compositions that reuse v10 built-in filter keys;
+- configured v9 filters that reuse v9 stable filter keys;
+- a custom attribute and custom filter definition with the same key.
+- repeated keys within `customAttributeFilterDefinitions`.
+
+Use the selection's `key` override when a workspace definition collides:
+
+```ts
+select: {
+  sauna: {
+    key: "privateSauna",
+    label: { "de-DE": "Sauna", "en-US": "Sauna" },
+    filter: true,
+  },
+}
+```
+
+Update query URLs and `rentalHighlightPrioritization` to the resolved key.
+
+## 6. Treat Categories as Display Labels
+
+Configuration keeps stable keys such as `OUTDOORS`. `getFilters` and rental
+attribute groups return localized labels such as `Außenbereich` or `Outdoor Area`.
+Do not compare output categories to stable keys. Customize wording with
+locale-nested overrides:
+
+```ts
+translationOverrides: {
+  "de-DE": {
+    "RentalAttributesCategory.OUTDOORS.label": "Draußen",
+  },
+}
+```
+
+## 7. Update Highlight Configuration
+
+Custom attributes appear in rental/search `highlights` only when their resolved key
+is listed in `rentalHighlightPrioritization`:
+
+```ts
+rentalHighlightPrioritization: ["bedrooms", customAttributes.keys.region, "bathrooms"];
+```
+
+The list remains authoritative for order. Registry contents do not reorder
+built-ins, duplicate keys render once, and a built-in metadata key shadows a
+same-named display-only custom attribute.
+
+## 8. Update Applied-Filter Handling
+
+Value-bearing applied filters now include canonical `value`:
+
+```ts
+{ key: "region", label: "Region: North", value: "north" }
+```
+
+Use `key` plus `value` to remove an exact filter. Labels remain localized
+presentation and are not identifiers. A scalar key may appear in both
+`appliedFilters` and `unusedFilterKeys` when one value applied and another was
+rejected.
+
+## 9. CLI and Untyped Options
+
+CLI JSON supplies catalog and selection **inputs**, not a finished registry:
+
+```json
+{
+  "customAttributes": {
+    "catalog": {
+      "privateSauna": {
+        "id": "GQYKYgMVh28X7VLGursbkt",
+        "type": "BOOLEAN"
+      }
+    },
+    "select": {
+      "privateSauna": {
+        "label": { "de-DE": "Sauna", "en-US": "Sauna" },
+        "filter": true
+      }
+    }
+  }
+}
+```
+
+The CLI uses `defineCustomAttributesFromUnknown` and applies the same runtime
+validation as typed configuration.
+
+## Recommended Verification
+
+1. Run `getFilters` for v9 and v10 in both locales.
+2. Confirm internal filters are absent while public compositions using them remain
+   executable.
+3. Inspect v9 GraphQL and v10 REST variables for one successful and one failed
+   composition.
+4. Verify renamed custom attributes render in rentals, search highlights, URLs, and
+   applied-filter chips.
+5. Verify `rentalHighlightPrioritization` order with and without custom attributes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v-office/website-sdk",
-  "version": "2.5.1",
+  "version": "2.8.0",
   "description": "Website-facing SDK facade backed by @v-office/sdk-core",
   "bin": {
     "website-sdk": "./dist/cli.mjs"
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "@graphql-typed-document-node/core": "3.2.0",
-    "@v-office/sdk-core": "^1.6.1",
+    "@v-office/sdk-core": "^1.8.0",
     "effect": "4.0.0-beta.85",
     "graphql": "16.14.2",
     "yaml": "^2.9.0"
@@ -72,6 +72,8 @@
     "lint:fix": "oxlint --fix .",
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check",
-    "check": "pnpm run typecheck && pnpm run lint"
+    "check": "pnpm run typecheck && pnpm run lint",
+    "test": "pnpm run build && node --test test/*.test.mjs",
+    "playground:custom-attributes": "pnpm run build && node --env-file=.env playground/custom-attributes.ts"
   }
 }