@decocms/blocks 8.5.1 → 8.6.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/dist/async/default.d.ts +10 -0
- package/dist/async/default.d.ts.map +1 -0
- package/dist/async/default.js +5 -0
- package/dist/async/default.js.map +1 -0
- package/dist/async/node.d.ts +3 -0
- package/dist/async/node.d.ts.map +1 -0
- package/dist/async/node.js +11 -0
- package/dist/async/node.js.map +1 -0
- package/dist/async/types.d.ts +6 -0
- package/dist/async/types.d.ts.map +1 -0
- package/dist/async/types.js +2 -0
- package/dist/async/types.js.map +1 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/v8/bucketing.d.ts +24 -0
- package/dist/v8/bucketing.d.ts.map +1 -0
- package/dist/v8/bucketing.js +78 -0
- package/dist/v8/bucketing.js.map +1 -0
- package/dist/v8/builtins/campaigns.d.ts +36 -0
- package/dist/v8/builtins/campaigns.d.ts.map +1 -0
- package/dist/v8/builtins/campaigns.js +107 -0
- package/dist/v8/builtins/campaigns.js.map +1 -0
- package/dist/v8/builtins/data.d.ts +2 -2
- package/dist/v8/builtins/data.js +2 -2
- package/dist/v8/builtins/experiments.d.ts +27 -0
- package/dist/v8/builtins/experiments.d.ts.map +1 -0
- package/dist/v8/builtins/experiments.js +62 -0
- package/dist/v8/builtins/experiments.js.map +1 -0
- package/dist/v8/builtins/index.d.ts.map +1 -1
- package/dist/v8/builtins/index.js +7 -2
- package/dist/v8/builtins/index.js.map +1 -1
- package/dist/v8/builtins/matchers.d.ts +0 -14
- package/dist/v8/builtins/matchers.d.ts.map +1 -1
- package/dist/v8/builtins/matchers.js +0 -19
- package/dist/v8/builtins/matchers.js.map +1 -1
- package/dist/v8/cli/builtins.d.ts +6 -0
- package/dist/v8/cli/builtins.d.ts.map +1 -1
- package/dist/v8/cli/builtins.js +19 -0
- package/dist/v8/cli/builtins.js.map +1 -1
- package/dist/v8/cli/check/index.d.ts.map +1 -1
- package/dist/v8/cli/check/index.js +231 -8
- package/dist/v8/cli/check/index.js.map +1 -1
- package/dist/v8/cli/schema/builtinSchemas.d.ts.map +1 -1
- package/dist/v8/cli/schema/builtinSchemas.js +76 -21
- package/dist/v8/cli/schema/builtinSchemas.js.map +1 -1
- package/dist/v8/cli/schema/generate.d.ts.map +1 -1
- package/dist/v8/cli/schema/generate.js +48 -2
- package/dist/v8/cli/schema/generate.js.map +1 -1
- package/dist/v8/client.d.ts +25 -0
- package/dist/v8/client.d.ts.map +1 -1
- package/dist/v8/client.js +58 -10
- package/dist/v8/client.js.map +1 -1
- package/dist/v8/cms.d.ts.map +1 -1
- package/dist/v8/cms.js +93 -42
- package/dist/v8/cms.js.map +1 -1
- package/dist/v8/content.d.ts +45 -0
- package/dist/v8/content.d.ts.map +1 -1
- package/dist/v8/content.js +68 -2
- package/dist/v8/content.js.map +1 -1
- package/dist/v8/current.d.ts +28 -0
- package/dist/v8/current.d.ts.map +1 -0
- package/dist/v8/current.js +77 -0
- package/dist/v8/current.js.map +1 -0
- package/dist/v8/draft.d.ts +40 -21
- package/dist/v8/draft.d.ts.map +1 -1
- package/dist/v8/draft.js +160 -25
- package/dist/v8/draft.js.map +1 -1
- package/dist/v8/experiments.d.ts +107 -0
- package/dist/v8/experiments.d.ts.map +1 -0
- package/dist/v8/experiments.js +292 -0
- package/dist/v8/experiments.js.map +1 -0
- package/dist/v8/hosts.d.ts +3 -2
- package/dist/v8/hosts.d.ts.map +1 -1
- package/dist/v8/hosts.js +3 -2
- package/dist/v8/hosts.js.map +1 -1
- package/dist/v8/index.d.ts +7 -5
- package/dist/v8/index.d.ts.map +1 -1
- package/dist/v8/index.js +6 -4
- package/dist/v8/index.js.map +1 -1
- package/dist/v8/remoteLoader.d.ts.map +1 -1
- package/dist/v8/remoteLoader.js +166 -20
- package/dist/v8/remoteLoader.js.map +1 -1
- package/dist/v8/resolver.d.ts +4 -2
- package/dist/v8/resolver.d.ts.map +1 -1
- package/dist/v8/resolver.js +11 -3
- package/dist/v8/resolver.js.map +1 -1
- package/dist/v8/settings.d.ts +16 -4
- package/dist/v8/settings.d.ts.map +1 -1
- package/dist/v8/settings.js +24 -21
- package/dist/v8/settings.js.map +1 -1
- package/dist/v8/types.d.ts +126 -21
- package/dist/v8/types.d.ts.map +1 -1
- package/package.json +35 -1
- package/src/async/default.ts +13 -0
- package/src/async/node.ts +12 -0
- package/src/async/types.ts +5 -0
- package/src/index.ts +4 -0
- package/src/v8/bucketing.ts +88 -0
- package/src/v8/builtins/campaigns.ts +120 -0
- package/src/v8/builtins/data.ts +2 -2
- package/src/v8/builtins/experiments.ts +72 -0
- package/src/v8/builtins/index.ts +7 -2
- package/src/v8/builtins/matchers.ts +0 -26
- package/src/v8/cli/builtins.ts +23 -0
- package/src/v8/cli/check/index.ts +289 -8
- package/src/v8/cli/schema/builtinSchemas.ts +82 -22
- package/src/v8/cli/schema/generate.ts +48 -3
- package/src/v8/client.ts +76 -10
- package/src/v8/cms.ts +108 -43
- package/src/v8/content.ts +86 -2
- package/src/v8/current.ts +98 -0
- package/src/v8/draft.ts +170 -30
- package/src/v8/experiments.ts +340 -0
- package/src/v8/hosts.ts +3 -2
- package/src/v8/index.ts +8 -4
- package/src/v8/remoteLoader.ts +190 -25
- package/src/v8/resolver.ts +14 -4
- package/src/v8/settings.ts +35 -29
- package/src/v8/types.ts +128 -19
package/src/v8/resolver.ts
CHANGED
|
@@ -12,7 +12,9 @@
|
|
|
12
12
|
* order and stop at the first `true` one (later rules never run, as in v7).
|
|
13
13
|
*
|
|
14
14
|
* A `Resolver` belongs to one client, so its memo (results per block function
|
|
15
|
-
* and canonical inputs) never outlives a request
|
|
15
|
+
* and canonical inputs) never outlives a request, and every block function it
|
|
16
|
+
* calls runs with that client as `currentClient()` (a lazy value called after
|
|
17
|
+
* the resolve returned included). Within the request the memo
|
|
16
18
|
* hands every occurrence of the same block the same result object, so results
|
|
17
19
|
* are read-only (see `Client` in ./types): mutating one in place would change
|
|
18
20
|
* the others, the class of bug behind the v7 layout-cache race.
|
|
@@ -21,9 +23,10 @@ import { RESERVED_NAMES } from "./builtins/index.ts";
|
|
|
21
23
|
import { isLazyBuiltin } from "./builtins/lazy.ts";
|
|
22
24
|
import { LEGACY_ALIASES, wrapLegacyVariants } from "./builtins/legacy.ts";
|
|
23
25
|
import { isMultivariateBuiltin } from "./builtins/multivariate.ts";
|
|
26
|
+
import { runWithClient } from "./current.ts";
|
|
24
27
|
import { errors, isResolutionError } from "./errors.ts";
|
|
25
28
|
import { canonicalKey, isPlainObject, type JsonObject, own } from "./json.ts";
|
|
26
|
-
import type { BlockFunction, Blocks, Lazy, Snapshot } from "./types.ts";
|
|
29
|
+
import type { BlockFunction, Blocks, Client, Lazy, Snapshot } from "./types.ts";
|
|
27
30
|
|
|
28
31
|
type Path = (string | number)[];
|
|
29
32
|
|
|
@@ -32,6 +35,8 @@ interface ResolverOptions {
|
|
|
32
35
|
blocks: Blocks;
|
|
33
36
|
/** The built-ins, with this CMS's `secret`. */
|
|
34
37
|
builtIns: Readonly<Blocks>;
|
|
38
|
+
/** The client this resolver belongs to: `currentClient()` while a block function runs. */
|
|
39
|
+
client?: Client;
|
|
35
40
|
/** Called once per name a saved block shares with a function. */
|
|
36
41
|
onCollision?: (name: string) => void;
|
|
37
42
|
/** Called after each block function runs (telemetry: spans and failures). */
|
|
@@ -42,15 +47,17 @@ export class Resolver {
|
|
|
42
47
|
readonly #snapshot: Snapshot;
|
|
43
48
|
readonly #blocks: Blocks;
|
|
44
49
|
readonly #builtIns: Readonly<Blocks>;
|
|
50
|
+
readonly #client: Client | undefined;
|
|
45
51
|
readonly #onCollision?: (name: string) => void;
|
|
46
52
|
readonly #onBlock?: ResolverOptions["onBlock"];
|
|
47
53
|
readonly #memo = new WeakMap<BlockFunction, Map<string, Promise<unknown>>>();
|
|
48
54
|
readonly #keys = new WeakMap<object, string | null>();
|
|
49
55
|
|
|
50
|
-
constructor({ snapshot, blocks, builtIns, onCollision, onBlock }: ResolverOptions) {
|
|
56
|
+
constructor({ snapshot, blocks, builtIns, client, onCollision, onBlock }: ResolverOptions) {
|
|
51
57
|
this.#snapshot = snapshot;
|
|
52
58
|
this.#blocks = blocks;
|
|
53
59
|
this.#builtIns = builtIns;
|
|
60
|
+
this.#client = client;
|
|
54
61
|
this.#onCollision = onCollision;
|
|
55
62
|
this.#onBlock = onBlock;
|
|
56
63
|
}
|
|
@@ -248,7 +255,10 @@ export class Resolver {
|
|
|
248
255
|
: await this.#resolveFields(inputs, path, chain, true);
|
|
249
256
|
const start = Date.now();
|
|
250
257
|
try {
|
|
251
|
-
const
|
|
258
|
+
const client = this.#client;
|
|
259
|
+
const value = await (client === undefined
|
|
260
|
+
? fn(resolved)
|
|
261
|
+
: runWithClient(client, () => fn(resolved)));
|
|
252
262
|
this.#onBlock?.(type, start, Date.now());
|
|
253
263
|
return value;
|
|
254
264
|
} catch (error) {
|
package/src/v8/settings.ts
CHANGED
|
@@ -9,9 +9,12 @@
|
|
|
9
9
|
* - A missing block, a block of another type, or a section that fails to
|
|
10
10
|
* resolve gives that section's defaults, still capped. Nothing rejects.
|
|
11
11
|
* - Telemetry rates are the lower of content's and `telemetry.limits`.
|
|
12
|
-
* - Preview hosts
|
|
13
|
-
* (
|
|
14
|
-
*
|
|
12
|
+
* - Preview hosts aren't content: Studio writes them into the release
|
|
13
|
+
* metadata (PO 2026-10-22), and `previewHosts` merges them with code's
|
|
14
|
+
* `preview.hosts`. A remote site with no list published (no `latest.json`
|
|
15
|
+
* yet, or one without `previewHosts`): every host. Content with no remote
|
|
16
|
+
* site: code's list, else every host. Metadata that couldn't be read:
|
|
17
|
+
* code's list alone, or none. `["*"]` means every host.
|
|
15
18
|
*/
|
|
16
19
|
import {
|
|
17
20
|
analyticsSection,
|
|
@@ -19,24 +22,20 @@ import {
|
|
|
19
22
|
SETTINGS_TYPE,
|
|
20
23
|
telemetrySection,
|
|
21
24
|
} from "./builtins/data.ts";
|
|
22
|
-
import {
|
|
23
|
-
|
|
24
|
-
formatHostPattern,
|
|
25
|
-
type HostPattern,
|
|
26
|
-
parseHostPattern,
|
|
27
|
-
patternWithin,
|
|
28
|
-
} from "./hosts.ts";
|
|
25
|
+
import type { ReleasePreviewHosts } from "./content.ts";
|
|
26
|
+
import { EVERY_HOST, formatHostPattern, type HostPattern, parseHostPattern } from "./hosts.ts";
|
|
29
27
|
import { isPlainObject } from "./json.ts";
|
|
30
28
|
import type { Client, CMSConfig, EffectiveSettings, Snapshot } from "./types.ts";
|
|
31
29
|
|
|
32
30
|
/** What code allows: the caps every section's content is held to. */
|
|
33
31
|
export interface SettingsCaps {
|
|
34
|
-
/** Code's `preview.hosts`, parsed; `undefined` when code sets none. */
|
|
35
|
-
hosts: readonly HostPattern[] | undefined;
|
|
36
32
|
limits: { errorSampleRate: number; traceSampleRate: number };
|
|
37
33
|
}
|
|
38
34
|
|
|
39
|
-
|
|
35
|
+
/** The settings a release's `CMS` block holds: every section but `preview`, which isn't content. */
|
|
36
|
+
export type SavedSettings = Omit<EffectiveSettings, "preview">;
|
|
37
|
+
|
|
38
|
+
const SECTIONS = ["telemetry", "analytics"] as const;
|
|
40
39
|
|
|
41
40
|
/**
|
|
42
41
|
* Code's `preview.hosts`, parsed. Throws a `TypeError` on anything that isn't
|
|
@@ -72,7 +71,7 @@ function parseCodePatterns(
|
|
|
72
71
|
}
|
|
73
72
|
|
|
74
73
|
/** The settings with nothing saved: every default, capped. */
|
|
75
|
-
export function defaultSettings(caps: SettingsCaps):
|
|
74
|
+
export function defaultSettings(caps: SettingsCaps): SavedSettings {
|
|
76
75
|
return effectiveSettings({}, caps);
|
|
77
76
|
}
|
|
78
77
|
|
|
@@ -85,7 +84,7 @@ export async function readSettings(
|
|
|
85
84
|
snapshot: Snapshot | undefined,
|
|
86
85
|
client: () => Client,
|
|
87
86
|
caps: SettingsCaps,
|
|
88
|
-
): Promise<
|
|
87
|
+
): Promise<SavedSettings> {
|
|
89
88
|
try {
|
|
90
89
|
const entry = snapshot?.blocks[SETTINGS_BLOCK];
|
|
91
90
|
if (!isPlainObject(entry) || entry.__resolveType !== SETTINGS_TYPE) {
|
|
@@ -125,10 +124,9 @@ function holdsBlock(value: unknown): boolean {
|
|
|
125
124
|
* The settings, deep-frozen: one object per release is handed to every caller,
|
|
126
125
|
* so a caller that writes to it would change it for every request.
|
|
127
126
|
*/
|
|
128
|
-
function effectiveSettings(value: Record<string, unknown>, caps: SettingsCaps):
|
|
127
|
+
function effectiveSettings(value: Record<string, unknown>, caps: SettingsCaps): SavedSettings {
|
|
129
128
|
const telemetry = telemetrySection(value.telemetry);
|
|
130
129
|
return deepFreeze({
|
|
131
|
-
preview: { hosts: effectiveHosts(value.preview, caps.hosts) },
|
|
132
130
|
telemetry: {
|
|
133
131
|
...telemetry,
|
|
134
132
|
errorSampleRate: Math.min(telemetry.errorSampleRate, caps.limits.errorSampleRate),
|
|
@@ -138,7 +136,7 @@ function effectiveSettings(value: Record<string, unknown>, caps: SettingsCaps):
|
|
|
138
136
|
});
|
|
139
137
|
}
|
|
140
138
|
|
|
141
|
-
function deepFreeze<T>(value: T): T {
|
|
139
|
+
export function deepFreeze<T>(value: T): T {
|
|
142
140
|
if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
|
|
143
141
|
Object.freeze(value);
|
|
144
142
|
for (const child of Object.values(value)) deepFreeze(child);
|
|
@@ -146,17 +144,25 @@ function deepFreeze<T>(value: T): T {
|
|
|
146
144
|
return value;
|
|
147
145
|
}
|
|
148
146
|
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
147
|
+
/**
|
|
148
|
+
* The preview hosts in effect, in their normal form, each once:
|
|
149
|
+
* - the release has a list: it (entries that aren't host patterns left out)
|
|
150
|
+
* plus code's `preview.hosts`;
|
|
151
|
+
* - a remote site published no list (`"every"`): every host (`["*"]`);
|
|
152
|
+
* - no remote site (`"local"`): code's `preview.hosts` when set, else every host;
|
|
153
|
+
* - the release metadata couldn't be read (`"unknown"`): code's alone, or
|
|
154
|
+
* none, so a failed read never opens previews.
|
|
155
|
+
*/
|
|
156
|
+
export function previewHosts(
|
|
157
|
+
release: ReleasePreviewHosts,
|
|
158
|
+
code: readonly HostPattern[] | undefined,
|
|
159
|
+
): string[] {
|
|
160
|
+
if (release === "every" || (release === "local" && code === undefined)) return [EVERY_HOST];
|
|
161
|
+
const listed = typeof release === "string" ? [] : release.map((raw) => parseHostPattern(raw));
|
|
162
|
+
const patterns = [...listed, ...(code ?? [])].filter(
|
|
163
|
+
(pattern): pattern is HostPattern => pattern !== null,
|
|
164
|
+
);
|
|
165
|
+
return unique(patterns.map(formatHostPattern));
|
|
160
166
|
}
|
|
161
167
|
|
|
162
168
|
function unique(values: string[]): string[] {
|
package/src/v8/types.ts
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
* (`/next/api-reference#types`) — every type here is documented there.
|
|
4
4
|
*/
|
|
5
5
|
import type { ReactNode } from "react";
|
|
6
|
+
import type { Assignments, Visitor } from "./experiments.ts";
|
|
6
7
|
|
|
7
8
|
// ---------------------------------------------------------------------------
|
|
8
9
|
// Blocks and content
|
|
@@ -41,6 +42,13 @@ export type Snapshot = {
|
|
|
41
42
|
* module, a build outside git), the bundled content counts as the oldest.
|
|
42
43
|
*/
|
|
43
44
|
committedAt?: string;
|
|
45
|
+
/**
|
|
46
|
+
* The hosts this release may be previewed on (host patterns), as Studio
|
|
47
|
+
* wrote them into the release metadata on delivery.decocms.com
|
|
48
|
+
* (`latest.json` and `revisions/<sha>.json`). Previews are checked against
|
|
49
|
+
* the current release's list; the bundled content has none.
|
|
50
|
+
*/
|
|
51
|
+
previewHosts?: string[];
|
|
44
52
|
};
|
|
45
53
|
|
|
46
54
|
/**
|
|
@@ -99,10 +107,14 @@ export interface Seo {
|
|
|
99
107
|
description: string;
|
|
100
108
|
}
|
|
101
109
|
|
|
102
|
-
/**
|
|
103
|
-
|
|
110
|
+
/**
|
|
111
|
+
* The built-in `page` block, resolved: without `seo`, the site's defaults
|
|
112
|
+
* apply. Its sections are whatever its section blocks return: React
|
|
113
|
+
* elements by default, or a site's descriptors (`Page<{ component, props }>`).
|
|
114
|
+
*/
|
|
115
|
+
export interface Page<Section = ReactNode> extends Route {
|
|
104
116
|
seo?: Seo;
|
|
105
|
-
sections:
|
|
117
|
+
sections: Section[];
|
|
106
118
|
}
|
|
107
119
|
|
|
108
120
|
/** The built-in `redirect` block. */
|
|
@@ -158,15 +170,20 @@ export interface Variant<T> {
|
|
|
158
170
|
* caps (see /next/built-in-blocks#cms-settings).
|
|
159
171
|
*/
|
|
160
172
|
export interface CMSSettings {
|
|
161
|
-
/** Host patterns previews are allowed on, within `createCMS`'s `preview.hosts`. */
|
|
162
|
-
preview?: { hosts?: string[] };
|
|
163
173
|
telemetry?: Telemetry;
|
|
164
174
|
analytics?: Analytics;
|
|
165
175
|
}
|
|
166
176
|
|
|
167
177
|
/** What `cms.settings()` returns: every section, defaults filled in, caps applied. */
|
|
168
178
|
export interface EffectiveSettings {
|
|
169
|
-
/**
|
|
179
|
+
/**
|
|
180
|
+
* The hosts previews are allowed on, as known in memory: the current
|
|
181
|
+
* release's `previewHosts` (Studio writes them into the release metadata)
|
|
182
|
+
* plus `createCMS`'s `preview.hosts`. A site with no list published (no
|
|
183
|
+
* `latest.json` yet, or one without `previewHosts`) and content with no
|
|
184
|
+
* remote site and no `preview.hosts` give `["*"]`, every host; an empty
|
|
185
|
+
* list, none (as before this process has read the release metadata).
|
|
186
|
+
*/
|
|
170
187
|
preview: { hosts: string[] };
|
|
171
188
|
telemetry: Required<Telemetry>;
|
|
172
189
|
analytics: Required<Analytics>;
|
|
@@ -266,8 +283,12 @@ export interface CMSConfig {
|
|
|
266
283
|
telemetry?: false | TelemetryConfig;
|
|
267
284
|
preview?: {
|
|
268
285
|
/**
|
|
269
|
-
*
|
|
270
|
-
*
|
|
286
|
+
* Hosts previews are allowed on besides the release's own (Studio writes
|
|
287
|
+
* those into the release metadata), in the host pattern format
|
|
288
|
+
* (/next/api-reference#host-patterns). Without `site`, the only list:
|
|
289
|
+
* left out, previews are allowed on every host. With `site`, it adds to
|
|
290
|
+
* the release's list; a site with no list published previews on every
|
|
291
|
+
* host anyway.
|
|
271
292
|
*/
|
|
272
293
|
hosts?: string[];
|
|
273
294
|
/**
|
|
@@ -304,13 +325,14 @@ export interface ListOptions<T> {
|
|
|
304
325
|
}
|
|
305
326
|
|
|
306
327
|
/**
|
|
307
|
-
* Reads one revision for one request.
|
|
328
|
+
* Reads one revision for one request, for one visitor, at one moment.
|
|
308
329
|
*
|
|
309
330
|
* Results are read-only. A client runs each block function once per distinct
|
|
310
331
|
* input, so the same block at two places in a request hands both places the
|
|
311
332
|
* same object; mutating it in place changes the other occurrence too. Copy a
|
|
312
333
|
* result before changing it. (The memo belongs to one client, so nothing is
|
|
313
|
-
* shared across requests
|
|
334
|
+
* shared across requests; it is also why tests and campaigns are decided once
|
|
335
|
+
* per client, however many rules ask.)
|
|
314
336
|
*/
|
|
315
337
|
export interface Client {
|
|
316
338
|
resolve<T = unknown>(target: unknown, options?: ResolveOptions): Promise<Result<T>>;
|
|
@@ -321,16 +343,88 @@ export interface Client {
|
|
|
321
343
|
* can't load, since there is no revision to report.
|
|
322
344
|
*/
|
|
323
345
|
revision(): Promise<string>;
|
|
346
|
+
/** Who is visiting, as passed to `cms.client()` (a frozen copy); `null` for none. */
|
|
347
|
+
readonly visitor: Visitor | null;
|
|
348
|
+
/**
|
|
349
|
+
* The version it reads: the release's commit SHA, or the draft pointer, as
|
|
350
|
+
* passed to `cms.client()`. For the current release, the SHA of the release
|
|
351
|
+
* it loaded (`undefined` until its first `resolve`, `list` or `revision()`).
|
|
352
|
+
*/
|
|
353
|
+
readonly version: string | undefined;
|
|
354
|
+
/** The date campaigns run at: the one passed to `cms.client()`, otherwise when the client was created. */
|
|
355
|
+
readonly date: Date;
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
/**
|
|
359
|
+
* What one client is created with, all read by the app outside blocks and
|
|
360
|
+
* passed in. The visitor and the date decide; `experiments` and `campaigns`
|
|
361
|
+
* override what they decide, name by name. Given every test and campaign and
|
|
362
|
+
* no visitor, a client is fully decided in advance (a page rendering what a
|
|
363
|
+
* proxy in front of it decided).
|
|
364
|
+
*/
|
|
365
|
+
export interface ClientOptions {
|
|
366
|
+
/**
|
|
367
|
+
* What to read: `undefined` (or `null`) for the current release; a
|
|
368
|
+
* published release's commit SHA (40 hex characters), read from hosted
|
|
369
|
+
* releases; or a draft pointer, the draft's changes over the current
|
|
370
|
+
* release. Only a version: a Studio link's moment and switched tests are
|
|
371
|
+
* the options below (`cms.readVersion(request)` reads all of them).
|
|
372
|
+
*/
|
|
373
|
+
version?: string | null;
|
|
374
|
+
/**
|
|
375
|
+
* Who is visiting (`readVisitor`, `parseVisitor` or `newVisitor` from
|
|
376
|
+
* `@decocms/blocks/experiments`): the saved block `experiments` decides
|
|
377
|
+
* its tests for them. Without one, every test not in `experiments` is off.
|
|
378
|
+
*/
|
|
379
|
+
visitor?: Visitor | null;
|
|
380
|
+
/**
|
|
381
|
+
* The moment the saved block `campaigns` checks its windows at
|
|
382
|
+
* (`client.date`). Default: when the client is created.
|
|
383
|
+
*/
|
|
384
|
+
date?: Date | null;
|
|
385
|
+
/**
|
|
386
|
+
* Tests on (`true`) or off (`false`) by name, whatever the visitor and the
|
|
387
|
+
* test's percentage; the others are decided for the visitor. A name the
|
|
388
|
+
* saved block `experiments` doesn't have stays out.
|
|
389
|
+
*/
|
|
390
|
+
experiments?: Partial<Assignments> | null;
|
|
391
|
+
/**
|
|
392
|
+
* Campaigns on (`true`) or off (`false`) by name, whatever their window;
|
|
393
|
+
* the others are checked at `date`. A name the saved block `campaigns`
|
|
394
|
+
* doesn't have stays out.
|
|
395
|
+
*/
|
|
396
|
+
campaigns?: Partial<Assignments> | null;
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
/**
|
|
400
|
+
* What a Studio link asks for (`cms.readVersion`, `parseVersion`): the
|
|
401
|
+
* version, and the preview's moment and the tests and campaigns it switches,
|
|
402
|
+
* in the shape of `ClientOptions`, so it spreads into `cms.client()`.
|
|
403
|
+
*/
|
|
404
|
+
export interface RequestVersion {
|
|
405
|
+
/** A draft pointer, or a published release's commit SHA. */
|
|
406
|
+
version: string;
|
|
407
|
+
/** The moment the preview shows (`__at`). */
|
|
408
|
+
date?: Date;
|
|
409
|
+
/** The tests the preview switches on or off (`__test=<name>=on|off`). */
|
|
410
|
+
experiments?: Assignments;
|
|
411
|
+
/** The campaigns the preview switches on or off (`__campaign=<name>=on|off`). */
|
|
412
|
+
campaigns?: Assignments;
|
|
324
413
|
}
|
|
325
414
|
|
|
326
415
|
export interface CMS {
|
|
327
|
-
/**
|
|
416
|
+
/**
|
|
417
|
+
* A client: the version it reads and the visitor it decides tests for, both
|
|
418
|
+
* passed in. Create one per request.
|
|
419
|
+
*/
|
|
420
|
+
client(options?: ClientOptions): Client;
|
|
421
|
+
/** A client reading the current release: `cms.client()`. */
|
|
328
422
|
forRelease(): Client;
|
|
329
423
|
/**
|
|
330
|
-
* A client reading the draft a pointer names:
|
|
331
|
-
* draft host (`*.decocms.com` and loopback by
|
|
332
|
-
* `createCMS({ preview: { draftHosts } })` replaces the list)
|
|
333
|
-
* server's production content.
|
|
424
|
+
* A client reading the draft a pointer names: `cms.client({ version: pointer })`.
|
|
425
|
+
* Its changes are fetched from a draft host (`*.decocms.com` and loopback by
|
|
426
|
+
* default; `createCMS({ preview: { draftHosts } })` replaces the list) and
|
|
427
|
+
* laid over this server's production content.
|
|
334
428
|
*/
|
|
335
429
|
forDraft(pointer: string): Client;
|
|
336
430
|
/** Ask the content source for newer content now; never throws. */
|
|
@@ -342,11 +436,26 @@ export interface CMS {
|
|
|
342
436
|
*/
|
|
343
437
|
settings(): Promise<EffectiveSettings>;
|
|
344
438
|
/**
|
|
345
|
-
*
|
|
346
|
-
* cookie
|
|
347
|
-
*
|
|
348
|
-
* (
|
|
439
|
+
* What a Studio link asks for: `?__draft=` first, then the `__deco_draft`
|
|
440
|
+
* cookie, holding a draft pointer or a published release's commit SHA,
|
|
441
|
+
* with the preview's moment (`__at`) and switched tests (`__test`) and
|
|
442
|
+
* campaigns (`__campaign`) as `date`, `experiments` and `campaigns`.
|
|
443
|
+
* `null` when neither is present, for `?__draft=off`, on a host outside
|
|
444
|
+
* the preview hosts (the current release's `previewHosts`, which Studio
|
|
445
|
+
* writes into the release metadata, plus `createCMS`'s `preview.hosts`;
|
|
446
|
+
* every host while the site has published no list, or without `site` and
|
|
447
|
+
* `preview.hosts`; no host while the metadata can't be read, besides
|
|
448
|
+
* `preview.hosts`), and for a value that doesn't parse (ignored,
|
|
449
|
+
* as if absent): in each case the request gets the current release. A
|
|
450
|
+
* draft and an older release's SHA are both checked against the current
|
|
451
|
+
* release's list.
|
|
452
|
+
*
|
|
453
|
+
* ```ts
|
|
454
|
+
* const client = cms.client({ visitor, ...(await cms.readVersion(request)) });
|
|
455
|
+
* ```
|
|
349
456
|
*/
|
|
457
|
+
readVersion(request: RequestLike): Promise<RequestVersion | null>;
|
|
458
|
+
/** The version alone (`readVersion(request)`'s `version`), under its earlier name. */
|
|
350
459
|
draftPointer(request: RequestLike): Promise<string | null>;
|
|
351
460
|
/**
|
|
352
461
|
* The `Set-Cookie` value that starts a preview (a valid `?__draft=` on an
|