@v-office/website-sdk 2.33.0 → 2.35.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +20 -9
- package/dist/cli.mjs +3 -3
- package/dist/{client-BSyJzzk0.mjs → client-BC5ukCcN.mjs} +143 -17
- package/dist/index.d.mts +18 -2
- package/dist/index.mjs +1 -1
- package/dist/instructions/CHANGELOG.md +2 -0
- package/dist/instructions/MIGRATION.md +2 -0
- package/dist/instructions/README.md +1 -0
- package/dist/instructions/availability.md +1 -1
- package/dist/instructions/booking.md +1 -1
- package/dist/instructions/contact.md +1 -1
- package/dist/instructions/creation.md +14 -3
- package/dist/instructions/custom-attributes.md +11 -8
- package/dist/instructions/quote.md +1 -1
- package/dist/instructions/regions.md +123 -0
- package/dist/instructions/search.md +5 -2
- package/dist/instructions/versions/2.34.0/CHANGELOG.md +18 -0
- package/dist/instructions/versions/2.34.0/MIGRATION.md +9 -0
- package/dist/instructions/versions/2.35.0/CHANGELOG.md +28 -0
- package/dist/instructions/versions/2.35.0/MIGRATION.md +39 -0
- package/dist/{operations-CUWcmNGK.mjs → operations-C1VMQYN2.mjs} +62 -1
- package/dist/{rentals-Be1Zs2DQ.mjs → rentals-tKaYW-Zz.mjs} +3 -3
- package/dist/{search-Dv5e8hNc.mjs → search-DibGd1I6.mjs} +3 -3
- package/dist/{to-rental-highlights-Dbnm6Y4_.mjs → to-rental-highlights-BdxQPpBU.mjs} +1 -1
- package/instructions/CHANGELOG.md +2 -0
- package/instructions/MIGRATION.md +2 -0
- package/instructions/README.md +1 -0
- package/instructions/availability.md +1 -1
- package/instructions/booking.md +1 -1
- package/instructions/contact.md +1 -1
- package/instructions/creation.md +14 -3
- package/instructions/custom-attributes.md +11 -8
- package/instructions/quote.md +1 -1
- package/instructions/regions.md +123 -0
- package/instructions/search.md +5 -2
- package/instructions/versions/2.34.0/CHANGELOG.md +18 -0
- package/instructions/versions/2.34.0/MIGRATION.md +9 -0
- package/instructions/versions/2.34.0/release.json +3 -0
- package/instructions/versions/2.35.0/CHANGELOG.md +28 -0
- package/instructions/versions/2.35.0/MIGRATION.md +39 -0
- package/instructions/versions/2.35.0/release.json +3 -0
- package/package.json +7 -2
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Regions
|
|
2
|
+
|
|
3
|
+
Regions group a site's rentals into a tree, for example Nordsee → Dornum → Dornumersiel.
|
|
4
|
+
`sdk.static.regions.getRegions` returns the tree in the same shape on both backends, so
|
|
5
|
+
region pages and the search's region field are the same code on v10 and v9.
|
|
6
|
+
|
|
7
|
+
| | v10 | v9 |
|
|
8
|
+
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
|
|
9
|
+
| Source | the websites service: editors arrange regions in the CMS (Websites → "Regionen"), and a website can have its own tree instead of the workspace's default | vOffice's region hierarchy, through the be-on! Hub |
|
|
10
|
+
| Regions per rental | several | one; it also counts for every region above it |
|
|
11
|
+
| Names | German and English | German; English when vOffice has it |
|
|
12
|
+
| Slugs | set by editors | generated from the names |
|
|
13
|
+
| Order | the editors' order | siblings by German name |
|
|
14
|
+
| Regions returned | every region in the tree | only regions holding a rental of the be-on key |
|
|
15
|
+
|
|
16
|
+
Regions are not a custom attribute. Do not read a "Region" custom attribute, and do not
|
|
17
|
+
select one in `defineCustomAttributes`: the tree replaces both.
|
|
18
|
+
|
|
19
|
+
## Reading The Tree
|
|
20
|
+
|
|
21
|
+
Read the tree once per build, at build time:
|
|
22
|
+
|
|
23
|
+
```ts
|
|
24
|
+
const regions = await sdk.static.regions.getRegions({
|
|
25
|
+
aiStudioWebsiteId: Number(process.env.WEB_ID),
|
|
26
|
+
});
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
`WEB_ID` is the AI Studio website id. The builder and the editor's dev server set it. v9
|
|
30
|
+
ignores it: vOffice keeps one region tree per customer.
|
|
31
|
+
|
|
32
|
+
Every call reads the whole tree, and neither backend caches it, so call it once and pass
|
|
33
|
+
the result on. Never call it per component, per page in the browser, or per request. A
|
|
34
|
+
failed read rejects, so the build stops instead of publishing a site without its regions.
|
|
35
|
+
A v10 website the service has no tree for returns an empty tree.
|
|
36
|
+
|
|
37
|
+
On v10, every change editors make to regions or region assignments queues a new build of
|
|
38
|
+
the website. A site never has to poll.
|
|
39
|
+
|
|
40
|
+
## The Result
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
type WebsiteRegions = {
|
|
44
|
+
isWebsiteOverride: boolean; // v10: true for the website's own tree; always false on v9
|
|
45
|
+
regions: readonly WebsiteRegion[];
|
|
46
|
+
};
|
|
47
|
+
|
|
48
|
+
type WebsiteRegion = {
|
|
49
|
+
id: string;
|
|
50
|
+
parentId: string | null; // null: top level
|
|
51
|
+
depth: number; // 0: top level
|
|
52
|
+
name: { "de-DE": string; "en-US": string };
|
|
53
|
+
slug: { "de-DE": string; "en-US": string };
|
|
54
|
+
path: { "de-DE": string; "en-US": string }; // "nordsee/dornum"
|
|
55
|
+
description: { "de-DE"?: string; "en-US"?: string };
|
|
56
|
+
ownRentalIds: readonly string[];
|
|
57
|
+
rentalIds: readonly string[];
|
|
58
|
+
};
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
- `regions` is depth first: every region comes before its subregions. Render it top to
|
|
62
|
+
bottom, or rebuild the tree from `parentId`.
|
|
63
|
+
- `name` and `slug` always hold both languages. When only one exists, the other language
|
|
64
|
+
uses it. `description` holds only the languages a description exists in.
|
|
65
|
+
- A slug is unique among its siblings, not across the tree. `path` joins the slugs of the
|
|
66
|
+
region's ancestors and its own with `/`, and is unique: use it as the URL path. On v9,
|
|
67
|
+
renaming a region in vOffice changes its slug and so its page URL.
|
|
68
|
+
- `ownRentalIds` are the rentals in the region itself. `rentalIds` adds every subregion's
|
|
69
|
+
rentals, each rental once. A region page lists `rentalIds`: "Nordsee" shows Dornum's
|
|
70
|
+
and Dornumersiel's rentals too.
|
|
71
|
+
- The ids are rental ids as `getRentals` returns them. Neither backend applies the SDK's
|
|
72
|
+
`rentalScope`: list only the rentals the site has.
|
|
73
|
+
|
|
74
|
+
## Region Pages And Rental URLs
|
|
75
|
+
|
|
76
|
+
Build one page per region from `path`, for example `/regionen/nordsee/dornum`, with the
|
|
77
|
+
name, the description and the rentals of `rentalIds`.
|
|
78
|
+
|
|
79
|
+
A rental keeps the one URL it already has. Never nest a rental's URL under a region: a
|
|
80
|
+
rental in several regions would get several URLs. Region pages link to the rental's own
|
|
81
|
+
page.
|
|
82
|
+
|
|
83
|
+
## Search
|
|
84
|
+
|
|
85
|
+
The search bar's region field and the `?region=` scope work in the browser, on facts the
|
|
86
|
+
build attaches to each rental. `@v-office/website-headless` turns the tree into both:
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
import {
|
|
90
|
+
cardSource,
|
|
91
|
+
rentalFactsMap,
|
|
92
|
+
regionOptions,
|
|
93
|
+
regionsByRental,
|
|
94
|
+
} from "@v-office/website-headless";
|
|
95
|
+
|
|
96
|
+
const options = regionOptions(regions, {
|
|
97
|
+
locale: "de-DE",
|
|
98
|
+
rentalIds: rentals.map((rental) => rental.id),
|
|
99
|
+
});
|
|
100
|
+
const regionsOf = regionsByRental(regions); // rental id → region ids
|
|
101
|
+
|
|
102
|
+
const sources = rentals.map((rental) =>
|
|
103
|
+
cardSource(rental, { rentalHref, regions: regionsOf[rental.id] ?? [] }),
|
|
104
|
+
);
|
|
105
|
+
const facts = rentalFactsMap(sources); // the search results' `facts`
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Pass `options` as they are as the `regions` prop of `SearchBar` from
|
|
109
|
+
`@v-office/website-components`; `createSearchForm` takes their `value`s. A region without
|
|
110
|
+
rentals is not offered, and `rentalIds` keeps a region whose rentals are all outside the
|
|
111
|
+
site's `rentalScope` out of the field and its counts.
|
|
112
|
+
|
|
113
|
+
The value of a region is its `id` (`?region=<id>`). A rental counts for a region and for
|
|
114
|
+
every region above it, so `?region=<id of Nordsee>` also finds the rentals in Dornum. To word a
|
|
115
|
+
`?region=` chip with the region's name instead of its id, curate a hidden `region` facet
|
|
116
|
+
with the same options:
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
{ kind: "facet", key: "region", label: "Region", options, hidden: true }
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
On v9 this replaces the Hub `region` filter (`search.md`, "A Filter By Region") for the
|
|
123
|
+
region field: it needs no Hub entry. A site that already uses the Hub filter keeps working.
|
package/instructions/search.md
CHANGED
|
@@ -296,6 +296,9 @@ Hub knows. The English labels are the German names; translate them.
|
|
|
296
296
|
|
|
297
297
|
#### A Filter By Region
|
|
298
298
|
|
|
299
|
+
For a region field in the search, prefer the region tree (`regions.md`): it works on v10
|
|
300
|
+
and v9 and needs no Hub entry.
|
|
301
|
+
|
|
299
302
|
`region` keeps rentals in one vOffice region and in its subregions: the region "Sylt"
|
|
300
303
|
also finds the rentals in "Westerland" and "Kampen". The be-on! Hub builds the list of
|
|
301
304
|
regions from the rentals of the be-on key.
|
|
@@ -501,7 +504,7 @@ for await (const page of sdk.live.search.searchPages({ locale: "de-DE", query })
|
|
|
501
504
|
`if (sdk.backend === "v9")`.
|
|
502
505
|
- The input is the `search` input without `cursor` and `limit`; the SDK pages itself.
|
|
503
506
|
- Every page is one `search` call and counts as one request for the rate limit, so
|
|
504
|
-
the SDK starts at most one page per second.
|
|
507
|
+
the SDK starts at most one page per second by default (`rateBudget`, see `creation.md`).
|
|
505
508
|
- A rental appears on one page only, even when a booking moves it between two pages.
|
|
506
509
|
- Each page carries its own `pageInfo`; `pageInfo.totalCount` is the total over all
|
|
507
510
|
pages.
|
|
@@ -922,7 +925,7 @@ Use flat `WebsiteSDKConfig` files and optional `WebsiteSDKOptions`.
|
|
|
922
925
|
|
|
923
926
|
For v10, config requires `searchEndpoint` (the full REST search URL) as of 2.5.0. See `creation.md` for `searchEndpoint` and the `customAttributes` option.
|
|
924
927
|
|
|
925
|
-
Custom filter definitions can extend accepted search query keys.
|
|
928
|
+
Custom filter definitions can extend accepted search query keys. By default, search requests start at most once a second, with at most five running or waiting at once; `rateBudget` changes both (see `creation.md`). A `searchAllRentalsAtOnce` search and a `mapSearch` each count as one request, including every backend request they make.
|
|
926
929
|
|
|
927
930
|
## CLI Usage
|
|
928
931
|
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# Changelog: 2.34.0
|
|
2
|
+
|
|
3
|
+
A server that serves many visitors through one SDK can widen the SDK's PMS request budget.
|
|
4
|
+
Websites keep the default and change nothing.
|
|
5
|
+
|
|
6
|
+
## Added
|
|
7
|
+
|
|
8
|
+
- The `rateBudget` option (`{ interval, maxQueueSize }`): how often the SDK may start a PMS
|
|
9
|
+
request of one kind, and how many of that kind may be running or waiting at once. It applies on v9 and v10 alike, to search, quote,
|
|
10
|
+
booking and contact, and on v10 also to availability and feedback. The default is unchanged:
|
|
11
|
+
one start a second, five at once. AI Studio's website chat, which shares one SDK per website
|
|
12
|
+
among all its visitors, widens it.
|
|
13
|
+
- An invalid `rateBudget` (a queue below 1, an interval that is not a positive duration) fails SDK
|
|
14
|
+
creation with an error that names it.
|
|
15
|
+
|
|
16
|
+
## Changed
|
|
17
|
+
|
|
18
|
+
- Nothing for existing code. Without `rateBudget`, every limit is what it was.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Changelog: 2.35.0
|
|
2
|
+
|
|
3
|
+
Websites can read their region tree, in one shape on v10 and v9, instead of a "Region"
|
|
4
|
+
custom attribute or the Hub `region` filter. Region pages and the search's region field
|
|
5
|
+
become the same code on both backends.
|
|
6
|
+
|
|
7
|
+
## Added
|
|
8
|
+
|
|
9
|
+
- `sdk.static.regions.getRegions({ aiStudioWebsiteId })`, a build-time read of the
|
|
10
|
+
website's region tree. Pass `Number(process.env.WEB_ID)`, which the builder and the
|
|
11
|
+
editor set.
|
|
12
|
+
- v10: the tree editors maintain in the CMS (Websites → "Regionen"); a website can have
|
|
13
|
+
its own tree. A rental can sit in several regions.
|
|
14
|
+
- v9: vOffice's region hierarchy through the be-on! Hub, with only the regions that hold
|
|
15
|
+
a rental of the be-on key. Slugs are generated from the names; siblings sort by German
|
|
16
|
+
name. `aiStudioWebsiteId` is ignored.
|
|
17
|
+
- Each region has German and English `name`, `slug` and `path` (`nordsee/dornum`, unique,
|
|
18
|
+
for region page URLs), an optional `description`, its `ownRentalIds`, and `rentalIds`,
|
|
19
|
+
which adds every subregion's rentals.
|
|
20
|
+
- The types `RegionsGetRegionsInput`, `WebsiteRegions` and `WebsiteRegion`.
|
|
21
|
+
- `regions.md` covers the data, region pages and the search's region field.
|
|
22
|
+
|
|
23
|
+
## Changed
|
|
24
|
+
|
|
25
|
+
- The custom attribute examples use a beach type instead of a region: a region is never
|
|
26
|
+
a custom attribute.
|
|
27
|
+
- The Hub `region` filter keeps working on v9; `search.md` points to the region tree for a
|
|
28
|
+
search's region field.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Migration: 2.34.0 to 2.35.0
|
|
2
|
+
|
|
3
|
+
No changes required. Follow step 2 only to take a site's regions from the region tree.
|
|
4
|
+
|
|
5
|
+
## 1. Upgrade
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
pnpm add @v-office/website-sdk@2.35.0
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
For step 2.3, also upgrade the headless package, which brings `regionOptions` and
|
|
12
|
+
`regionsByRental`:
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
pnpm add @v-office/website-headless@1.2.0
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## 2. Take the regions from the region tree
|
|
19
|
+
|
|
20
|
+
1. Read the tree once per build:
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
const regions = await sdk.static.regions.getRegions({
|
|
24
|
+
aiStudioWebsiteId: Number(process.env.WEB_ID),
|
|
25
|
+
});
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
2. v10: remove the code that reads the "Region" custom attribute values, and remove the
|
|
29
|
+
attribute from `defineCustomAttributes` if it was selected there. v9: a region field
|
|
30
|
+
fed by the Hub `region` filter can move to the tree; the Hub entry can stay.
|
|
31
|
+
3. Build the search bar's regions and each rental's region facts from the tree with
|
|
32
|
+
`regionOptions` and `regionsByRental` from `@v-office/website-headless` 1.2.0. Region
|
|
33
|
+
values become region ids, so links that carry an old `?region=<name>` no longer narrow
|
|
34
|
+
the search: update them.
|
|
35
|
+
4. Region pages take their URL from `path` and list `rentalIds`. A rental keeps its own
|
|
36
|
+
URL.
|
|
37
|
+
|
|
38
|
+
An empty tree is normal on v10 until editors create regions in the CMS: the region field
|
|
39
|
+
then hides itself. See `regions.md`.
|
package/package.json
CHANGED
|
@@ -1,8 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@v-office/website-sdk",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.35.0",
|
|
4
4
|
"description": "Website-facing SDK facade backed by @v-office/sdk-core",
|
|
5
5
|
"license": "UNLICENSED",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/vofficeGmbh/ai-studio.git",
|
|
9
|
+
"directory": "sdks/website"
|
|
10
|
+
},
|
|
6
11
|
"bin": {
|
|
7
12
|
"website-sdk": "./dist/cli.mjs"
|
|
8
13
|
},
|
|
@@ -43,7 +48,7 @@
|
|
|
43
48
|
},
|
|
44
49
|
"dependencies": {
|
|
45
50
|
"@graphql-typed-document-node/core": "3.2.0",
|
|
46
|
-
"@v-office/sdk-core": "1.
|
|
51
|
+
"@v-office/sdk-core": "1.27.0",
|
|
47
52
|
"effect": "4.0.0-rc.115",
|
|
48
53
|
"graphql": "17.0.2",
|
|
49
54
|
"yaml": "^2.9.0"
|