@decocms/blocks 8.5.2 → 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.
Files changed (121) hide show
  1. package/dist/async/default.d.ts +10 -0
  2. package/dist/async/default.d.ts.map +1 -0
  3. package/dist/async/default.js +5 -0
  4. package/dist/async/default.js.map +1 -0
  5. package/dist/async/node.d.ts +3 -0
  6. package/dist/async/node.d.ts.map +1 -0
  7. package/dist/async/node.js +11 -0
  8. package/dist/async/node.js.map +1 -0
  9. package/dist/async/types.d.ts +6 -0
  10. package/dist/async/types.d.ts.map +1 -0
  11. package/dist/async/types.js +2 -0
  12. package/dist/async/types.js.map +1 -0
  13. package/dist/index.d.ts +1 -1
  14. package/dist/index.d.ts.map +1 -1
  15. package/dist/index.js +1 -1
  16. package/dist/index.js.map +1 -1
  17. package/dist/v8/bucketing.d.ts +24 -0
  18. package/dist/v8/bucketing.d.ts.map +1 -0
  19. package/dist/v8/bucketing.js +78 -0
  20. package/dist/v8/bucketing.js.map +1 -0
  21. package/dist/v8/builtins/campaigns.d.ts +36 -0
  22. package/dist/v8/builtins/campaigns.d.ts.map +1 -0
  23. package/dist/v8/builtins/campaigns.js +107 -0
  24. package/dist/v8/builtins/campaigns.js.map +1 -0
  25. package/dist/v8/builtins/data.d.ts +2 -2
  26. package/dist/v8/builtins/data.js +2 -2
  27. package/dist/v8/builtins/experiments.d.ts +27 -0
  28. package/dist/v8/builtins/experiments.d.ts.map +1 -0
  29. package/dist/v8/builtins/experiments.js +62 -0
  30. package/dist/v8/builtins/experiments.js.map +1 -0
  31. package/dist/v8/builtins/index.d.ts.map +1 -1
  32. package/dist/v8/builtins/index.js +7 -2
  33. package/dist/v8/builtins/index.js.map +1 -1
  34. package/dist/v8/builtins/matchers.d.ts +0 -14
  35. package/dist/v8/builtins/matchers.d.ts.map +1 -1
  36. package/dist/v8/builtins/matchers.js +0 -19
  37. package/dist/v8/builtins/matchers.js.map +1 -1
  38. package/dist/v8/cli/builtins.d.ts +6 -0
  39. package/dist/v8/cli/builtins.d.ts.map +1 -1
  40. package/dist/v8/cli/builtins.js +19 -0
  41. package/dist/v8/cli/builtins.js.map +1 -1
  42. package/dist/v8/cli/check/index.d.ts.map +1 -1
  43. package/dist/v8/cli/check/index.js +231 -8
  44. package/dist/v8/cli/check/index.js.map +1 -1
  45. package/dist/v8/cli/schema/builtinSchemas.d.ts.map +1 -1
  46. package/dist/v8/cli/schema/builtinSchemas.js +76 -21
  47. package/dist/v8/cli/schema/builtinSchemas.js.map +1 -1
  48. package/dist/v8/cli/schema/generate.d.ts.map +1 -1
  49. package/dist/v8/cli/schema/generate.js +48 -2
  50. package/dist/v8/cli/schema/generate.js.map +1 -1
  51. package/dist/v8/client.d.ts +25 -0
  52. package/dist/v8/client.d.ts.map +1 -1
  53. package/dist/v8/client.js +58 -10
  54. package/dist/v8/client.js.map +1 -1
  55. package/dist/v8/cms.d.ts.map +1 -1
  56. package/dist/v8/cms.js +93 -42
  57. package/dist/v8/cms.js.map +1 -1
  58. package/dist/v8/content.d.ts +45 -0
  59. package/dist/v8/content.d.ts.map +1 -1
  60. package/dist/v8/content.js +68 -2
  61. package/dist/v8/content.js.map +1 -1
  62. package/dist/v8/current.d.ts +28 -0
  63. package/dist/v8/current.d.ts.map +1 -0
  64. package/dist/v8/current.js +77 -0
  65. package/dist/v8/current.js.map +1 -0
  66. package/dist/v8/draft.d.ts +40 -21
  67. package/dist/v8/draft.d.ts.map +1 -1
  68. package/dist/v8/draft.js +160 -25
  69. package/dist/v8/draft.js.map +1 -1
  70. package/dist/v8/experiments.d.ts +107 -0
  71. package/dist/v8/experiments.d.ts.map +1 -0
  72. package/dist/v8/experiments.js +292 -0
  73. package/dist/v8/experiments.js.map +1 -0
  74. package/dist/v8/hosts.d.ts +3 -2
  75. package/dist/v8/hosts.d.ts.map +1 -1
  76. package/dist/v8/hosts.js +3 -2
  77. package/dist/v8/hosts.js.map +1 -1
  78. package/dist/v8/index.d.ts +7 -5
  79. package/dist/v8/index.d.ts.map +1 -1
  80. package/dist/v8/index.js +6 -4
  81. package/dist/v8/index.js.map +1 -1
  82. package/dist/v8/remoteLoader.d.ts.map +1 -1
  83. package/dist/v8/remoteLoader.js +166 -20
  84. package/dist/v8/remoteLoader.js.map +1 -1
  85. package/dist/v8/resolver.d.ts +4 -2
  86. package/dist/v8/resolver.d.ts.map +1 -1
  87. package/dist/v8/resolver.js +11 -3
  88. package/dist/v8/resolver.js.map +1 -1
  89. package/dist/v8/settings.d.ts +16 -4
  90. package/dist/v8/settings.d.ts.map +1 -1
  91. package/dist/v8/settings.js +24 -21
  92. package/dist/v8/settings.js.map +1 -1
  93. package/dist/v8/types.d.ts +126 -21
  94. package/dist/v8/types.d.ts.map +1 -1
  95. package/package.json +35 -1
  96. package/src/async/default.ts +13 -0
  97. package/src/async/node.ts +12 -0
  98. package/src/async/types.ts +5 -0
  99. package/src/index.ts +4 -0
  100. package/src/v8/bucketing.ts +88 -0
  101. package/src/v8/builtins/campaigns.ts +120 -0
  102. package/src/v8/builtins/data.ts +2 -2
  103. package/src/v8/builtins/experiments.ts +72 -0
  104. package/src/v8/builtins/index.ts +7 -2
  105. package/src/v8/builtins/matchers.ts +0 -26
  106. package/src/v8/cli/builtins.ts +23 -0
  107. package/src/v8/cli/check/index.ts +289 -8
  108. package/src/v8/cli/schema/builtinSchemas.ts +82 -22
  109. package/src/v8/cli/schema/generate.ts +48 -3
  110. package/src/v8/client.ts +76 -10
  111. package/src/v8/cms.ts +108 -43
  112. package/src/v8/content.ts +86 -2
  113. package/src/v8/current.ts +98 -0
  114. package/src/v8/draft.ts +170 -30
  115. package/src/v8/experiments.ts +340 -0
  116. package/src/v8/hosts.ts +3 -2
  117. package/src/v8/index.ts +8 -4
  118. package/src/v8/remoteLoader.ts +190 -25
  119. package/src/v8/resolver.ts +14 -4
  120. package/src/v8/settings.ts +35 -29
  121. package/src/v8/types.ts +128 -19
@@ -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. Within the request the memo
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 value = await fn(resolved);
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) {
@@ -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: content's entries that fall within code's `preview.hosts`
13
- * (all of them when code sets none); without the field, code's list, or
14
- * every host.
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
- EVERY_HOST,
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
- const SECTIONS = ["preview", "telemetry", "analytics"] as const;
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): EffectiveSettings {
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<EffectiveSettings> {
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): EffectiveSettings {
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
- function effectiveHosts(preview: unknown, code: readonly HostPattern[] | undefined): string[] {
150
- const saved = isPlainObject(preview) && Array.isArray(preview.hosts) ? preview.hosts : undefined;
151
- if (saved === undefined) return code ? unique(code.map(formatHostPattern)) : [EVERY_HOST];
152
- const kept: string[] = [];
153
- for (const raw of saved) {
154
- const pattern = parseHostPattern(raw);
155
- if (pattern === null) continue; // not a pattern: left out
156
- if (code && !code.some((cap) => patternWithin(pattern, cap))) continue;
157
- kept.push(formatHostPattern(pattern));
158
- }
159
- return unique(kept);
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
- /** The built-in `page` block, resolved: without `seo`, the site's defaults apply. */
103
- export interface Page extends Route {
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: ReactNode[];
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
- /** `["*"]` means every host; an empty list, none. */
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
- * The most content may allow previews on, in the host pattern format
270
- * (/next/api-reference#host-patterns). Without it, content may allow any host.
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
- /** A client reading the current release. */
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: its changes, fetched from a
331
- * draft host (`*.decocms.com` and loopback by default;
332
- * `createCMS({ preview: { draftHosts } })` replaces the list), over this
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
- * The request's draft pointer: `?__draft=` first, then the `__deco_draft`
346
- * cookie. `null` when neither is present, for `?__draft=off`, on a host
347
- * outside `settings().preview.hosts`, and for a value that doesn't parse
348
- * (ignored, as if absent): in each case the request gets the release.
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