@v-office/website-sdk 2.7.0 → 2.9.0

package/instructions/custom-attributes.md

@@ -0,0 +1,560 @@
+# Custom Attributes
+
+Custom attributes are workspace-specific rental metadata: a sauna flag, a region, an
+occupancy score, a marketing text. This document covers how to configure them, how
+they behave on each backend, and what changes when a site moves from `v9` to `v10`.
+
+They serve three separate concerns, and each is configured independently:
+
+- **Filtering**: a stable query key a search UI can advertise and a visitor can use.
+- **Display**: a localized value rendered in rental attributes or highlights.
+- **Backend identity**: the workspace-specific v10 definition ID or v9 rental-data
+  field the SDK must talk to.
+
+## Two Halves: Catalog and Policy
+
+Configuration is a join of two things that have different owners.
+
+|               | Owner                 | Contains                                                            |
+| ------------- | --------------------- | ------------------------------------------------------------------- |
+| **Catalog**   | the workspace backend | definition ID, backend type, option values                          |
+| **Selection** | your site             | which attributes to use, labels, filter exposure, display, category |
+
+You never restate a catalog fact in your configuration. `defineCustomAttributes`
+joins the two, validates the result, and returns a registry the SDK consumes.
+
+```ts
+import { defineCustomAttributes, defineWebsiteSDKOptions } from "@v-office/website-sdk";
+
+const customAttributes = defineCustomAttributes({
+  catalog,
+  select: {
+    sauna: { label: { "de-DE": "Sauna", "en-US": "Sauna" } },
+    region: {
+      label: { "de-DE": "Region", "en-US": "Region" },
+      filter: true,
+      optionLabels: {
+        north: { "de-DE": "Norden", "en-US": "North" },
+        south: { "de-DE": "Süden", "en-US": "South" },
+      },
+    },
+  },
+});
+
+const options = defineWebsiteSDKOptions({ customAttributes });
+```
+
+Invalid configuration throws while the SDK is being configured, which for a static
+site means the build fails. Every problem is reported in one pass:
+
+```
+Invalid custom attribute configuration (3 problems):
+  - sauna.label: missing a label for de-DE; the catalog supplies none, so it must be authored
+  - amenityTags: backend type MULTI_SELECT has no canonical SDK value type yet, so it cannot be selected
+  - region.optionLabels: a filterable option attribute needs a label for every option; missing south, east, west
+```
+
+## The Catalog
+
+A `Record` keyed by the backend's definition key:
+
+```ts
+type CustomAttributeCatalogDefinitionInput = {
+  id: string; // 22-character v10 definition ID
+  type:
+    | "BOOLEAN"
+    | "NUMBER"
+    | "SINGLE_SELECT"
+    | "TEXT"
+    | "LOCALE_TEXT"
+    | "MULTI_SELECT"
+    | "LOCALE_DAY"
+    | "LOCAL_TIME"
+    | "LOCAL_TIMERANGE"
+    | "MONETARY_VALUE";
+  options?: readonly string[]; // SINGLE_SELECT identities; values only, no labels
+  label?: { "de-DE"?: string; "en-US"?: string };
+};
+```
+
+### Where it comes from
+
+```ts
+import { fetchCustomAttributeCatalog } from "@v-office/website-sdk";
+
+const catalog = await fetchCustomAttributeCatalog({ config });
+```
+
+This is a v10-only build-time read using `apiEndpoint` and `accessToken`, never a
+per-request lookup. Nothing is generated and nothing is committed, so definition IDs
+are never copied by hand and selected definitions stay aligned with the backend. It calls
+`customattributes_listPublicCustomAttributeDefinition`; the configured token must be
+authorized for that operation. When a website token lacks that permission, fetch the
+catalog in an authorized build environment or pin a literal catalog. The operation
+returns IDs, keys, types, and option identities, but no localized labels; author
+labels in `select`. Definitions that the SDK cannot map are omitted with a warning,
+and the remaining catalog is schema-validated. If multiple backend definitions share
+one key, every definition for that ambiguous key is omitted with one warning rather
+than binding whichever row arrived first.
+
+You can also pin a literal catalog. Doing so is the only way to get compile-time
+checking of your selection keys and option values, because a fetched value is
+widened to `Record<string, …>`:
+
+```ts
+const catalog = {
+  sauna: { id: "GQYKYgMVh28X7VLGursbkt", type: "BOOLEAN" },
+} as const satisfies CustomAttributeCatalogInput;
+```
+
+Both forms are accepted and validated identically. The only difference is _when_ a
+mistake surfaces: a literal catalog catches an unknown key in the editor, a fetched
+one catches it when `defineCustomAttributes` runs.
+
+### Backend types the SDK can use
+
+| Backend type         | SDK type  | Notes                                        |
+| -------------------- | --------- | -------------------------------------------- |
+| `BOOLEAN`            | `boolean` |                                              |
+| `NUMBER`             | `int`     | base-10 integers only                        |
+| `SINGLE_SELECT`      | `option`  | option identities come from the catalog      |
+| `TEXT`               | `string`  | exact match                                  |
+| `LOCALE_TEXT`        | —         | unsupported: no locale-selection policy yet  |
+| `MULTI_SELECT`       | —         | unsupported: no AND/OR semantics yet         |
+| date, time, monetary | —         | unsupported: no canonical type or parser yet |
+
+Selecting an unsupported definition fails with a precise message rather than being
+approximated. A definition you do not select is simply ignored, so unsupported types
+elsewhere in the workspace never block a build.
+
+## The Selection
+
+Every field is optional except a label, and each default is chosen so that omitting
+a field cannot expose or broaden anything.
+
+```ts
+type CustomAttributeOverridesInput = {
+  key?: string; // public query key, when the catalog key cannot be one
+  label?: { "de-DE"?: string; "en-US"?: string };
+  category?: CustomAttributeCategoryKey; // defaults to "OTHER"
+  display?: boolean; // defaults to true
+  v9?: string; // p_* rental-data binding
+  filter?:
+    | boolean // `true` means public
+    | "internal"
+    | {
+        exposure?: "public" | "internal";
+        numericBounds?: { min: number; max: number }; // int only, UI hint
+        allowsFalseValue?: boolean; // boolean only, defaults to false
+      };
+  optionLabels?: Record<string, { "de-DE": string; "en-US": string }>; // option only
+};
+```
+
+| Field              | Default                   | Why that default is safe                                                       |
+| ------------------ | ------------------------- | ------------------------------------------------------------------------------ |
+| `filter`           | absent                    | silence never creates a public query capability                                |
+| `display`          | `true`                    | only public definitions can be selected, so there is nothing private to expose |
+| `allowsFalseValue` | `false`                   | silence never broadens matching                                                |
+| `category`         | `OTHER`                   | presentation only — grouping, never reachability                               |
+| `label`            | the catalog label, if any | **no safe default** — see below                                                |
+
+`category` governs **two** things: which group the filter appears under in
+`getFilters`, and which group the value appears under in the rental attribute list.
+Both backends resolve it the same way, so switching v9 → v10 never moves an
+attribute between groups. An attribute whose category matches a built-in group
+joins that group rather than starting a parallel one.
+
+You author the category **key** (`ESSENTIALS`); output carries its **localized
+label** (`Grundlagen` in `de-DE`), exactly like a built-in filter or attribute. Never
+match on the output string — it changes with locale. Override the wording through
+`translationOverrides` on `RentalAttributesCategory.<KEY>.label` if you need to.
+
+`label` is the one field that is effectively required. Humanizing a key produces
+English-ish text that is simply wrong for `de-DE`, so when the catalog supplies no
+label you must author one. A partial override is merged over a partial catalog
+label; the merged result must cover every locale.
+
+A display-only option attribute may omit `optionLabels`; an unlabeled option then
+renders with its raw catalog identity. Once `filter` is enabled, every catalog option
+must have a complete label for each supported locale because `getFilters` must return
+a usable localized option list.
+
+### Renaming a key
+
+Backend definition keys are human-authored and routinely contain spaces or
+punctuation, which cannot appear in a query string. Use `key` to give such a
+definition a public name:
+
+```ts
+select: {
+  "Wäschepaket inkl.": {
+    key: "linenPackage",
+    label: { "de-DE": "Wäschepaket inklusive", "en-US": "Linen package included" },
+    filter: true,
+  },
+}
+```
+
+The attribute is then `linenPackage` everywhere downstream — in URLs, in
+`getFilters`, in applied filters, and in highlight references. A catalog key that is
+already URL-safe (`[A-Za-z0-9_-]+`) is used as-is and needs no override. Forgetting
+the override on a key that needs one fails with:
+
+```
+- Wäschepaket inkl.: the catalog key is not usable as a public query key.
+  Add a "key" override containing only letters, digits, underscore, or hyphen.
+```
+
+Renaming is product policy, so it lives in the selection rather than the catalog:
+the catalog is re-read on every build and an authored field there would be lost.
+
+### Public data only
+
+**The website SDK only ever sees definitions the backend marks `PUBLIC`.** That is
+enforced by the operations it calls: `listPublicCustomAttributeDefinition` for the
+catalog and `listPublicCustomAttribute` for values. A private definition never
+reaches the SDK at all, and there is no filter to opt out of.
+
+Because of that, visibility is **not** part of any type you touch. There is no
+visibility field on a catalog entry, none on a resolved attribute, and no rule you
+have to remember to apply. Privacy is enforced where the data lives rather than by
+configuration that could be got wrong.
+
+This also closes an inference path that a display-only rule would leave open. An
+`internal` filter is hidden from `getFilters` but is still parseable from a query
+string, so if a private definition were reachable at all, a visitor who guessed the
+key could send `?ownerNote=…` and infer values from which rentals came back. Nothing
+private is reachable, so there is nothing to infer.
+
+Because the values read is also a public operation, the backend decides at request
+time what a website may see. That covers a definition whose visibility changed after
+your site was built, which a build-time snapshot could not.
+
+### Exposure versus display
+
+Within public data, two decisions remain independent:
+
+|                 | Meaning                           |
+| --------------- | --------------------------------- |
+| filter exposure | `public`, `internal`, or absent   |
+| display         | whether the value may be rendered |
+
+| Filter exposure | `getFilters` | query parsing | compositions   | display     |
+| --------------- | ------------ | ------------- | -------------- | ----------- |
+| `public`        | included     | allowed       | allowed        | independent |
+| `internal`      | excluded     | allowed       | allowed        | independent |
+| absent          | excluded     | not applied   | invalid target | independent |
+
+`internal` is a UI-visibility choice, not a security boundary — it keeps a filter out
+of `getFilters` while leaving it usable by your own code and by compositions. Use it
+for filters you drive yourself, never to hide sensitive data; the data behind it is
+public either way.
+
+## Value Types
+
+| Type      | Accepted query values                                                   | Rendered as                                   |
+| --------- | ----------------------------------------------------------------------- | --------------------------------------------- |
+| `boolean` | `?key`, `?key=true`, `?key=1`; `false`/`0` only with `allowsFalseValue` | the label alone when true, omitted when false |
+| `int`     | base-10 integers only — no whitespace, fractions, `1e3`, or `0x1f`      | `Label: 1.234` (localized)                    |
+| `string`  | any non-empty value, exact match                                        | `Label: value`                                |
+| `option`  | only values the catalog declares                                        | `Label: <option label>`                       |
+
+Rendering dispatches on the declared type, never on the runtime shape of the value.
+Both backends return values as strings, so a shape-based guess would read an `int`
+of `"1"` as a boolean and drop a `string` of `"0"`.
+
+When a value cannot be read as the declared type — an `int` of `"1.5"` or an option
+value the catalog does not declare — the attribute is omitted rather than rendering
+something misleading. A false boolean and an absent value are also omitted.
+
+Scalar filters take **one** value. Given `?region=north,south`, the first valid value
+is applied, but the key also remains in `unusedFilterKeys` because the extra token was
+not applied. Combining scalar values would depend on backend semantics that are not
+specified, and an AND of two option values can only return nothing.
+
+`numericBounds` are UI hints for building a control. The parser does not enforce
+them, so an advertised bound always round-trips.
+
+## Highlights and Attributes
+
+A custom attribute appears in `highlights` only when its key is listed in
+`rentalHighlightPrioritization`, which is the ordered allowlist:
+
+```ts
+const options = defineWebsiteSDKOptions({
+  customAttributes,
+  rentalHighlightPrioritization: [
+    "bedrooms",
+    customAttributes.keys.region, // checked for a literal typed registry
+    "bathrooms",
+  ],
+});
+```
+
+The `keys` object is literal-typed when `defineCustomAttributes` receives a literal
+catalog and selection. The JSON and `defineCustomAttributesFromUnknown` paths still
+validate at runtime, but their keys are widened to `Record<string, string>` and
+cannot catch a typo at compile time.
+
+A built-in metadata key shadows a same-named custom attribute even when the built-in
+value is absent — custom attributes are strictly a fallback there.
+
+`getRentals` renders custom attributes into both `attributes` and `highlights`;
+`search` renders them into `highlights` only.
+
+In `attributes`, a custom attribute is placed in the group named by its resolved
+`category`, alongside built-in attributes of that category rather than in a separate
+bucket. The default `OTHER` therefore groups everything you did not categorize
+together — set `category` when you want an attribute to sit with related built-ins.
+
+Values are looked up by the attribute's **resolved** key, so a definition renamed
+through `key` renders under its new name on every path.
+
+## Backend Behaviour
+
+The same registry is passed to both backends. Each uses the part it can bind.
+
+| Registry entry | v10              | v9      |
+| -------------- | ---------------- | ------- |
+| `id` only      | filter + display | ignored |
+| `v9` only      | ignored          | display |
+| both           | filter + display | display |
+
+### v10
+
+Filtering and display both work. A filter resolves its stable key to the catalog
+definition ID and sends `{ customAttributeDefinitionId, customAttributeValue }` to
+REST search. Returned values resolve back through the ID index before
+rendering.
+
+### v9
+
+Display only. v9 has **no custom-attribute search path**, so a custom attribute is
+never advertised by v9 `getFilters` and a custom-attribute query key is always
+reported in `unusedFilterKeys`. Values come from rental data, addressed by the `v9`
+binding:
+
+```ts
+select: {
+  privateSauna: {
+    label: { "de-DE": "Sauna", "en-US": "Sauna" },
+    v9: "p_14418", // rental-data field, never the public query key
+    filter: true, // executes on v10; ignored by v9
+  },
+}
+```
+
+An attribute that exists only in v9 has no catalog entry, so every fact is authored
+and it carries no `filter` field at all:
+
+```ts
+const customAttributes = defineCustomAttributes({
+  catalog,
+  select: {},
+  v9Only: {
+    thatchedRoof: {
+      v9: "p_14418",
+      type: "boolean",
+      label: { "de-DE": "Reetdach", "en-US": "Thatched roof" },
+    },
+    locationType: {
+      v9: "p_10005",
+      type: "option",
+      label: { "de-DE": "Lage", "en-US": "Location type" },
+      // For v9 the authored keys are the option identities.
+      optionLabels: {
+        village: { "de-DE": "Dorf", "en-US": "Village" },
+        solitary: { "de-DE": "Alleinlage", "en-US": "Secluded" },
+      },
+    },
+  },
+});
+```
+
+## Backend Filters and Compositions
+
+These are **not** custom attributes and stay in `customAttributeFilterDefinitions`:
+
+- `backendFilter`: a backend-native search key, in practice a v9 hub filter.
+  Advertised and executed by v9; ignored by v10.
+- `composition`: a virtual boolean filter that expands into other configured
+  filters. Advertised only when every configured leaf can execute on the active
+  backend with its configured value.
+
+Compositions may reference stable v9 built-ins directly; `backendFilter` is only for
+additional v9 keys. SDK configuration does not create those keys in Hub; ask someone
+at be-on! with Hub access to add or confirm the filter before configuring it.
+
+```ts
+const options = defineWebsiteSDKOptions({
+  customAttributes,
+  customAttributeFilterDefinitions: [
+    {
+      key: "atLeastTwoBedrooms",
+      source: "backendFilter",
+      type: "boolean",
+      category: "LIVING_SLEEPING",
+      label: { "de-DE": "Mind. zwei Schlafzimmer", "en-US": "At least two bedrooms" },
+      searchable: true,
+      internal: false,
+    },
+    {
+      key: "premium",
+      source: "composition",
+      type: "complex",
+      category: "ESSENTIALS",
+      label: { "de-DE": "Premium", "en-US": "Premium" },
+      searchable: true,
+      internal: false,
+      expression: { all: [{ filter: "atLeastTwoBedrooms", value: true }] },
+    },
+  ],
+});
+```
+
+A composition expression supports equality leaves combined with `all`. It is
+**all-or-nothing at the backend-payload level**: every leaf is validated against the
+active backend before any generated input is committed. If any leaf is unknown,
+unsupported, or has an invalid configured value, no composition-generated leaf
+reaches GraphQL or REST and only the composition key is reported in
+`unusedFilterKeys`. A direct query filter remains independent even when a failed
+composition references the same key.
+
+When every leaf succeeds, `appliedFilters` contains the composition and its expanded
+leaf entries. Consumers that render removable filter chips should decide whether to
+show both levels or collapse leaf entries belonging to a visible composition.
+
+An executable `internal` leaf may be used by a public composition without becoming
+a standalone `getFilters` item. A composition cannot reference another composition;
+option normalization rejects nested compositions while recursive expansion is
+unsupported.
+
+`category` remains a stable authored key in configuration. `getFilters` translates
+it through `RentalAttributesCategory.<KEY>.label`, including for `backendFilter` and
+`composition` definitions, and returns the localized display label.
+
+Every search query key must have one owner. Option normalization rejects period and
+occupancy keys such as `start`, `adults`, and `pets`; v10 also rejects filterable
+custom attributes and compositions that reuse generated v10 filter keys; v9 rejects
+configured filters that reuse stable v9 filter keys. A custom attribute and a
+configured custom filter also cannot share a key, and two configured filter
+definitions cannot repeat one. Use the custom attribute `key` override when a
+workspace definition collides.
+
+## Moving from v9 to v10
+
+Switching backend changes capability. The registry and backend-specific filter
+catalog determine which filters and compositions are executable, so `getFilters`
+may add or remove entries.
+
+### What is unchanged
+
+- The configuration object. One `customAttributes` registry serves both backends.
+- Stable query keys, and therefore existing URLs.
+- Display: an attribute with both an `id` and a `v9` binding renders on both.
+- Backend filters and compositions remain configured, but are advertised only on
+  backends that can execute all required leaves.
+
+### What you gain
+
+- **Custom-attribute filtering.** Definitions with a catalog `id` and an enabled
+  filter start appearing in `getFilters` and start being applied by search. On v9
+  those same keys were reported in `unusedFilterKeys`.
+
+### What you must change
+
+1. **Supply a catalog.** v9 needs none; v10 resolves definition IDs through it.
+   Without one, no custom attribute has an `id`, so none can filter.
+2. **Add `id` bindings.** A v9-only entry keeps working for display but never
+   filters. Move it from `v9Only` into `select` with a `v9` override to get both.
+3. **Re-check backend filters.** `source: "backendFilter"` is a v9 hub concept with
+   no v10 equivalent. v10 does not advertise or execute those keys. Any filter you
+   need on v10 must become a custom attribute or a built-in filter.
+4. **Re-check compositions.** A composition is only as good as its leaves. One whose
+   leaves are v9 backend filters is omitted from v10 `getFilters`; if its key still
+   arrives through a saved or hand-written URL, it is reported unused without
+   applying any leaf.
+
+### Worth knowing
+
+- v9 exposes a small set of hub filters that have no v10 counterpart; a key such as
+  `pool` may exist on v9 and not on v10.
+- v10 advertises far more built-in filters, so `getFilters` returns a much longer
+  list. Query keys are guaranteed unique within one response on both backends.
+
+### A configuration that works on both
+
+```ts
+const customAttributes = defineCustomAttributes({
+  catalog, // empty object on a v9-only site
+  select: {
+    privateSauna: {
+      label: { "de-DE": "Sauna", "en-US": "Sauna" },
+      v9: "p_14418", // v9 renders it
+      filter: true, // v10 also filters on it
+    },
+  },
+});
+```
+
+On v9 this renders a sauna highlight and reports `?privateSauna=true` as unused. On
+v10 the same object renders the highlight _and_ advertises and applies the filter.
+Nothing in the site's URLs or configuration changes.
+
+## Untyped Configuration
+
+Configuration that arrives without static types — a JSON options file, the CLI, or
+an object assembled at runtime — goes through the same join:
+
+```ts
+import { defineCustomAttributesFromUnknown } from "@v-office/website-sdk";
+
+const customAttributes = defineCustomAttributesFromUnknown(JSON.parse(raw));
+```
+
+The CLI does this for you. An options file passes the _inputs_, not a finished
+registry:
+
+```json
+{
+  "customAttributes": {
+    "catalog": {
+      "privateSauna": { "id": "GQYKYgMVh28X7VLGursbkt", "type": "BOOLEAN" }
+    },
+    "select": {
+      "privateSauna": {
+        "label": { "de-DE": "Sauna", "en-US": "Sauna" },
+        "filter": true
+      }
+    }
+  },
+  "rentalHighlightPrioritization": ["bedrooms", "privateSauna"]
+}
+```
+
+```sh
+website-sdk --backend v10 --options ./website-sdk-options.json filters --locale de-DE
+```
+
+Every rule applies identically on this path; only the compile-time key and option
+unions are lost.
+
+## Reference
+
+Exported from `@v-office/website-sdk`:
+
+- `defineCustomAttributes` — join a catalog with a selection, typed.
+- `defineCustomAttributesFromUnknown` — the same join for untyped input.
+- `fetchCustomAttributeCatalog` — read the catalog from the definitions API.
+- `parseCustomAttributeCatalog` — validate a catalog that arrives as plain data.
+- `CustomAttributeCatalogSchema` — the catalog schema.
+
+Types: `CustomAttributeCatalog`, `CustomAttributeCatalogInput`,
+`CustomAttributeCatalogDefinitionInput`, `CustomAttributeCategoryKey`,
+`CustomAttributeOverridesInput`, `CustomAttributeSelection`, `CustomAttributeRegistry`,
+`CustomAttributeRegistrySnapshot`, `ResolvedCustomAttribute`,
+`V9OnlyCustomAttributeInput`.
+
+Related: `creation.md` for options, `filter.md` for `getFilters`, `search.md` for
+query parsing and applied filters, `rentals.md` for attributes and highlights.