@v-office/website-sdk 1.2.1 → 2.1.0

package/dist/instructions/creation.md

@@ -0,0 +1,223 @@
+# Creation
+
+## Service
+
+Create the SDK with `createWebsiteSDK`:
+
+```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();
+}
+```
+
+`createWebsiteSDK` returns the public `WebsiteSDK` facade with `static`, `live`, and `dispose` APIs. Call `dispose()` when the SDK instance is no longer needed. For v9, `dispose()` currently resolves without tearing down shared runtime state because the v9 facade does not hold one.
+
+## Configuration
+
+Backend config is required when creating the SDK.
+
+`v9`:
+
+```ts
+const sdk = createWebsiteSDK({
+  config: {
+    backend: "v9",
+    graphqlUrl: "https://example.com/graphql",
+    v1ApiBaseUrl: "https://example.com/api/v1",
+    v0ApiBaseUrl: "https://example.com/api/v0",
+    apiKey: "...",
+    imageProxyBaseUrl: "https://images.example.com",
+    rentalDataAttributes: ["name", "description"],
+  },
+});
+```
+
+`v10`:
+
+```ts
+const sdk = createWebsiteSDK({
+  config: {
+    backend: "v10",
+    apiEndpoint: "https://api.example.com/graphql",
+    accessToken: "...",
+    imageBaseUrl: "https://images.example.com",
+  },
+});
+```
+
+For v10, `backend: "v10"` is optional in TypeScript, but including it is clearer when config files are shared with the CLI.
+
+## WebsiteSDKOptions
+
+`options` is optional and is passed separately from backend config:
+
+```ts
+const options = defineWebsiteSDKOptions({
+  rentalScope: {
+    propertyId: "property-1",
+  },
+  rentalHighlightPrioritization: ["bedrooms", "bathrooms", "maxPersons", "wifi"],
+  rentalPropertyHighlightPrioritization: ["wifi", "parking"],
+  customAttributeFilterDefinitions: [],
+  translationOverrides: {},
+});
+```
+
+`defineWebsiteSDKOptions` is a typed identity helper. It is useful when defining options separately because TypeScript checks the option structure without changing the runtime value. `defineCMSSDKOptions` remains exported as a compatibility alias, but new code should use `defineWebsiteSDKOptions`.
+
+```ts
+type WebsiteSDKOptions = {
+  translationOverrides?: TranslationOverrides;
+  customAttributeFilterDefinitions?: readonly CustomAttributeFilterDefinition[];
+  rentalHighlightPrioritization?: readonly RentalHighlightPrioritizationKey[];
+  rentalPropertyHighlightPrioritization?: readonly RentalPropertyHighlightPrioritizationKey[];
+  rentalScope?: RentalScope;
+};
+```
+
+Unset options are normalized by the SDK:
+
+- `customAttributeFilterDefinitions` defaults to `[]`.
+- `rentalHighlightPrioritization` defaults to the SDK default rental highlight order.
+- `rentalPropertyHighlightPrioritization` defaults to the SDK default property highlight order.
+- `rentalScope` defaults to `{}`.
+- `translationOverrides` is omitted unless provided.
+
+## Rental Scope
+
+Use `rentalScope` to restrict all rental lists and searches created by this SDK instance:
+
+```ts
+const options = defineWebsiteSDKOptions({
+  rentalScope: {
+    propertyId: "property-1",
+  },
+});
+```
+
+`propertyId` is a unified SDK option:
+
+- `v9` static rentals are filtered by `voffice_facility_id`.
+- `v9` live search maps it to the generated `VofficeFilter.falicityid` field.
+- `v10` static rentals and live search map it to the generated `rentals_RentalSummaryFilter.propertyId` field.
+
+The scope is always applied internally and is not returned by `static.filter.getFilters(...)`. Use it for website-level or tenant-level constraints.
+
+## Custom Attribute Filter Definitions
+
+Use `customAttributeFilterDefinitions` to add SDK-known filter keys for custom attributes, v9 backend filters, or composed filters:
+
+```ts
+const options = defineWebsiteSDKOptions({
+  customAttributeFilterDefinitions: [
+    {
+      key: "region",
+      source: "customAttribute",
+      category: "ESSENTIALS",
+      label: {
+        "de-DE": "Region",
+        "en-US": "Region",
+      },
+      type: "option",
+      options: [
+        {
+          value: "north",
+          label: {
+            "de-DE": "Nord",
+            "en-US": "North",
+          },
+        },
+      ],
+      searchable: true,
+      internal: false,
+    },
+  ],
+});
+```
+
+Supported filter types:
+
+- `boolean`: accepts enabled query values such as `?key`, `?key=true`, or `?key=1`.
+- `int`: accepts integer query values and can expose optional `numericBounds` for UI controls.
+- `option`: accepts one of the configured `options` values and exposes those options through `getFilters`.
+- `string`: accepts any non-empty query value as an exact raw value.
+- `complex`: composition-only type that expands one boolean query-string filter into other configured filters.
+
+Supported sources:
+
+- `customAttribute`: backed by custom attributes.
+- `backendFilter`: backed by backend-defined search filter keys, mainly for v9 hub filters.
+- `composition`: expands one boolean query-string filter into other configured filters.
+
+Visibility:
+
+- `internal: false` exposes searchable filters through `static.filter.getFilters(...)`.
+- `internal: true` keeps filters usable by search and compositions but hides them from `getFilters`.
+- `searchable: false` keeps custom attributes as display metadata only.
+
+## Translation Overrides
+
+Use `translationOverrides` to override SDK translation keys:
+
+```ts
+const options = defineWebsiteSDKOptions({
+  translationOverrides: {
+    "de-DE": {
+      "filter.wifi.label": "WLAN",
+    },
+  },
+});
+```
+
+Overrides are applied by the SDK translation service and affect labels generated by filters, rentals, search, availability, and quote output.
+
+## CLI Usage
+
+The CLI reads flat `WebsiteSDKConfig` JSON files and separate `WebsiteSDKOptions` JSON files:
+
+```sh
+website-sdk --backend v10 --config ./website-sdk-config.json --options ./website-sdk-options.json rentals --locale de-DE
+```
+
+Example `website-sdk-config.v10.json`:
+
+```json
+{
+  "backend": "v10",
+  "apiEndpoint": "https://api.example.com/graphql",
+  "accessToken": "...",
+  "imageBaseUrl": "https://images.example.com"
+}
+```
+
+Example `website-sdk-options.json`:
+
+```json
+{
+  "rentalScope": {
+    "propertyId": "property-1"
+  },
+  "rentalHighlightPrioritization": ["bedrooms", "bathrooms", "maxPersons", "wifi"],
+  "customAttributeFilterDefinitions": [],
+  "translationOverrides": {}
+}
+```

package/dist/instructions/document-structured-json.md

@@ -0,0 +1,100 @@
+# Structured Document JSON
+
+## Service
+
+Use the v10 static documents API to fetch published terms and privacy policy revisions:
+
+```ts
+if (sdk.backend === "v10") {
+  const documents = await sdk.static.documents.getTermsAndPrivacyPolicy({ locale: "de-DE" });
+}
+```
+
+Input is `{ locale: "de-DE" | "en-US" }`. Output is `Promise<DocumentsGetTermsAndPrivacyPolicyOutput>` with optional `terms` and `privacyPolicy`, each shaped as `{ subject, data }`.
+
+This API is v10-only, has no dedicated CLI command yet, and returns `data` as a string. When `data` contains structured document JSON, render it with the rules below.
+
+## At A Glance
+
+The document is a JSON array. Each item is either plain text or a structured tool object.
+
+```json
+[
+  "plain text",
+  "\n",
+  {
+    "tool": "link",
+    "settings": { "href": "https://example.com" },
+    "children": [{ "tool": "bold", "children": ["Example"] }]
+  }
+]
+```
+
+## Base Rules
+
+- Root value: always an array. An empty document is `[]`.
+- Text part: any JSON string. `"\n"` means a line break. A string may also contain embedded `\n`.
+- Tool part: `{ "tool": string, "settings"?: object, "children"?: array }`.
+- `tool`: required name that defines how to interpret `settings` and `children`.
+- `settings`: optional metadata object. Omit it when unused; do not rely on `null`.
+- `children`: optional nested document array with the same shape as the root.
+- Unknown tools have no standard meaning. Preserve them when round-tripping; skip or fallback gracefully when rendering.
+- Internal cursor/selection marker tools are editor state, not document content, and should not be stored.
+
+## Tool Sets
+
+A document may use any subset of these tools. Custom producers may add more tool names.
+
+## Built-In Tool Reference
+
+- `bold`, `italic`, `underline`: formatting wrappers with `children`.
+- `color`: `settings.textColor`; optional `settings.backgroundColor`; has `children`.
+- `leading`: `settings.leading`; values: `tight`, `snug`, `normal`, `relaxed`, `loose`; has `children`.
+- `alignment`: `settings.alignment`; values: `left`, `center`, `right`, `justify`; has `children`.
+- `headline`: `settings.level` from `1` to `6`; has `children`.
+- `horizontalLine`: no settings or children.
+- `list`: `settings.numbered`; `children` are `item` tool objects.
+- `item`: structural list item; meaningful inside `list`; uses `children`.
+- `table`: `settings.headRows`, `settings.headColumns`; `children` are `row` tool objects.
+- `row`: structural table row; meaningful inside `table`; `children` are `column` tool objects.
+- `column`: structural table cell; meaningful inside `row`; uses `children`.
+- `link`: `settings.href`; optional `settings.embedded` with `type` and `size`; non-embedded links use `children`.
+- `image`: `settings.url`; optional `settings.caption`, `settings.cid`.
+- `placeholder`: `settings.domain`, `settings.field`, `settings.type`; renders as `{{domain.field}}` in reading mode.
+- `conditional`: `settings.service`, `settings.conditions[]` with `{ "condition": string, "fields": object }`; has conditional `children`.
+- `snippet`: `settings.service`, `settings.topLevelEntity`, `settings.snippet`, `settings.config`; optional `settings.inline`.
+- `ai`: optional `settings.prompt`, `settings.loadingText`; optional replacement `children`; reading mode renders empty text.
+- `quote`: optional `settings.author`, `settings.datetime`, `settings.messengerId`, `settings.html`; treat HTML as untrusted and sanitize before rendering.
+- `knowledgeBaseReference`: `settings.key`; has `children`.
+- `knowledgeBaseLink`: `settings.articleId`; has `children`.
+- `alert`: `settings.type`; values: `info`, `success`, `warning`, `error`; has `children`.
+- `code`: `settings.code`; optional `settings.block`, `settings.language`.
+
+Link embed `type` values: `youtube`, `figmaFile`, `figmaDesign`, `figmaBoard`, `heygen`, `heygenEmbeds`, `synthesia`, `iframe`.
+
+Link embed `size` values: `small`, `medium`, `large`.
+
+Code `language` values: `typescript`, `javascript`, `xml`, `json`, `yaml`, `css`, `graphql`.
+
+## Edge Cases
+
+- Missing `children` and empty `children: []` both mean no nested content.
+- Missing `settings` is valid only when the tool has no required settings.
+- Some tools ignore `children` even if present, for example `image`, `code`, `quote`, `snippet`, and embedded `link`.
+- `placeholder`, `conditional`, `snippet`, and `knowledgeBaseLink` need external application context to render fully.
+- `conditional.children` should only be displayed when its conditions pass.
+- `snippet` content is rendered from `settings` by an external renderer, not stored in `children`.
+- `quote.settings.html` can contain HTML; consumers should sanitize it even if it was already sanitized by the producer.
+- `ai` is transient editing state. Consumers that render final read-only content should treat it as empty.
+- `cid` on `image` may reference an attached resource instead of using only `url`.
+- Structural tools `item`, `row`, and `column` are not meaningful as top-level document blocks.
+
+## Compact Examples
+
+```json
+{ "tool": "headline", "settings": { "level": 2 }, "children": ["Heading"] }
+{ "tool": "list", "settings": { "numbered": false }, "children": [{ "tool": "item", "children": ["Item"] }] }
+{ "tool": "image", "settings": { "url": "https://example.com/image.png", "caption": "Optional" } }
+{ "tool": "placeholder", "settings": { "domain": "User", "field": "email", "type": "string" } }
+{ "tool": "code", "settings": { "block": true, "language": "typescript", "code": "const value = 1" } }
+```

package/dist/instructions/filter.md

@@ -0,0 +1,158 @@
+# Filter
+
+## Service
+
+Use the static filter API to fetch localized search filter definitions:
+
+```ts
+const filters = await sdk.static.filter.getFilters({ locale: "de-DE" });
+```
+
+The service is implemented for both `v9` and `v10` backends and returns normalized filters for building search UIs.
+
+## Input
+
+```ts
+type FilterGetFiltersInput = {
+  locale: "de-DE" | "en-US";
+};
+```
+
+Sample:
+
+```json
+{
+  "locale": "de-DE"
+}
+```
+
+## Output
+
+Returns `Promise<FilterGetFiltersOutput>`, an array of filter definitions.
+
+Sample:
+
+```json
+[
+  {
+    "searchParameterQueryKey": "wifi",
+    "label": "WiFi",
+    "category": "ESSENTIALS",
+    "type": "BooleanFilter"
+  },
+  {
+    "searchParameterQueryKey": "bedrooms",
+    "label": "Bedrooms",
+    "category": "ROOMS",
+    "type": "IntFilter",
+    "numericBounds": {
+      "min": 1,
+      "max": 8
+    }
+  },
+  {
+    "searchParameterQueryKey": "region",
+    "label": "Region",
+    "category": "LOCATION",
+    "type": "OptionFilter",
+    "options": [
+      {
+        "value": "north",
+        "label": "North"
+      }
+    ]
+  }
+]
+```
+
+Filter variants:
+
+- `BooleanFilter`: on/off query parameter.
+- `IntFilter`: numeric query parameter, optionally with `numericBounds`.
+- `OptionFilter`: query parameter with localized selectable `options`.
+
+## Configuration
+
+`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"
+}
+```
+
+Optional `WebsiteSDKOptions` can add public custom filters:
+
+```json
+{
+  "customAttributeFilterDefinitions": [
+    {
+      "key": "region",
+      "source": "customAttribute",
+      "category": "ESSENTIALS",
+      "label": {
+        "de-DE": "Region",
+        "en-US": "Region"
+      },
+      "type": "option",
+      "options": [
+        {
+          "value": "north",
+          "label": {
+            "de-DE": "Norden",
+            "en-US": "North"
+          }
+        }
+      ],
+      "searchable": true,
+      "internal": false
+    }
+  ],
+  "translationOverrides": {}
+}
+```
+
+Only custom definitions with `searchable: true` and `internal: false` are exposed by `getFilters`.
+
+For v10, `getFilters` also exposes the mapped BooleanFilter `pets`, labeled `Dogs welcome` / `Hunde willkommen`. It maps to one pet in search occupancy; use `petsCount` when the UI needs an exact pet count instead.
+
+## CLI Usage
+
+Fetch filters with environment-based config:
+
+```sh
+website-sdk --backend v9 filters --locale en-US
+website-sdk --backend v10 filters --locale de-DE
+```
+
+Use files instead of environment variables:
+
+```sh
+website-sdk --backend v10 --config ./website-sdk-config.json --options ./website-sdk-options.json filters --locale de-DE
+```
+
+Output defaults to JSON. Use `--output pretty` for inspected terminal output:
+
+```sh
+website-sdk --backend v10 filters --locale de-DE --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`.