@decocms/blocks 8.1.0-next.3 → 8.1.0-next.4

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 (97) hide show
  1. package/dist/index.d.ts +1 -1
  2. package/dist/index.d.ts.map +1 -1
  3. package/dist/index.js +1 -1
  4. package/dist/index.js.map +1 -1
  5. package/dist/protocol/secrets.d.ts.map +1 -1
  6. package/dist/protocol/secrets.js +9 -2
  7. package/dist/protocol/secrets.js.map +1 -1
  8. package/dist/protocol/server/assets.d.ts +1 -1
  9. package/dist/protocol/server/assets.js +1 -1
  10. package/dist/v8/builtins/data.d.ts +21 -5
  11. package/dist/v8/builtins/data.d.ts.map +1 -1
  12. package/dist/v8/builtins/data.js +47 -6
  13. package/dist/v8/builtins/data.js.map +1 -1
  14. package/dist/v8/builtins/index.d.ts.map +1 -1
  15. package/dist/v8/builtins/index.js +2 -3
  16. package/dist/v8/builtins/index.js.map +1 -1
  17. package/dist/v8/canonical.d.ts +1 -1
  18. package/dist/v8/cli/check/index.d.ts.map +1 -1
  19. package/dist/v8/cli/check/index.js +13 -1
  20. package/dist/v8/cli/check/index.js.map +1 -1
  21. package/dist/v8/cli/index.d.ts +2 -1
  22. package/dist/v8/cli/index.d.ts.map +1 -1
  23. package/dist/v8/cli/index.js +2 -1
  24. package/dist/v8/cli/index.js.map +1 -1
  25. package/dist/v8/cli/run.d.ts.map +1 -1
  26. package/dist/v8/cli/run.js +2 -9
  27. package/dist/v8/cli/run.js.map +1 -1
  28. package/dist/v8/cli/schema/builtinSchemas.d.ts.map +1 -1
  29. package/dist/v8/cli/schema/builtinSchemas.js +48 -28
  30. package/dist/v8/cli/schema/builtinSchemas.js.map +1 -1
  31. package/dist/v8/cli/schema/tsProgram.d.ts +10 -0
  32. package/dist/v8/cli/schema/tsProgram.d.ts.map +1 -1
  33. package/dist/v8/cli/schema/tsProgram.js +31 -0
  34. package/dist/v8/cli/schema/tsProgram.js.map +1 -1
  35. package/dist/v8/cli/schema/typeToSchema.d.ts.map +1 -1
  36. package/dist/v8/cli/schema/typeToSchema.js +15 -1
  37. package/dist/v8/cli/schema/typeToSchema.js.map +1 -1
  38. package/dist/v8/cli/serve/server.d.ts +0 -4
  39. package/dist/v8/cli/serve/server.d.ts.map +1 -1
  40. package/dist/v8/cli/serve/server.js +20 -46
  41. package/dist/v8/cli/serve/server.js.map +1 -1
  42. package/dist/v8/cms.d.ts +5 -2
  43. package/dist/v8/cms.d.ts.map +1 -1
  44. package/dist/v8/cms.js +180 -23
  45. package/dist/v8/cms.js.map +1 -1
  46. package/dist/v8/content.d.ts +14 -0
  47. package/dist/v8/content.d.ts.map +1 -1
  48. package/dist/v8/content.js +28 -0
  49. package/dist/v8/content.js.map +1 -1
  50. package/dist/v8/draft.d.ts +9 -12
  51. package/dist/v8/draft.d.ts.map +1 -1
  52. package/dist/v8/draft.js +8 -4
  53. package/dist/v8/draft.js.map +1 -1
  54. package/dist/v8/hosts.d.ts +55 -0
  55. package/dist/v8/hosts.d.ts.map +1 -0
  56. package/dist/v8/hosts.js +197 -0
  57. package/dist/v8/hosts.js.map +1 -0
  58. package/dist/v8/index.d.ts +4 -3
  59. package/dist/v8/index.d.ts.map +1 -1
  60. package/dist/v8/index.js +3 -2
  61. package/dist/v8/index.js.map +1 -1
  62. package/dist/v8/remoteLoader.d.ts.map +1 -1
  63. package/dist/v8/remoteLoader.js +14 -2
  64. package/dist/v8/remoteLoader.js.map +1 -1
  65. package/dist/v8/settings.d.ts +27 -0
  66. package/dist/v8/settings.d.ts.map +1 -0
  67. package/dist/v8/settings.js +130 -0
  68. package/dist/v8/settings.js.map +1 -0
  69. package/dist/v8/telemetry.d.ts +13 -3
  70. package/dist/v8/telemetry.d.ts.map +1 -1
  71. package/dist/v8/telemetry.js +31 -32
  72. package/dist/v8/telemetry.js.map +1 -1
  73. package/dist/v8/types.d.ts +56 -2
  74. package/dist/v8/types.d.ts.map +1 -1
  75. package/package.json +1 -1
  76. package/src/index.ts +3 -3
  77. package/src/protocol/secrets.ts +10 -2
  78. package/src/protocol/server/assets.ts +1 -1
  79. package/src/v8/builtins/data.ts +56 -7
  80. package/src/v8/builtins/index.ts +2 -3
  81. package/src/v8/canonical.ts +1 -1
  82. package/src/v8/cli/check/index.ts +23 -1
  83. package/src/v8/cli/index.ts +2 -1
  84. package/src/v8/cli/run.ts +3 -8
  85. package/src/v8/cli/schema/builtinSchemas.ts +49 -28
  86. package/src/v8/cli/schema/tsProgram.ts +27 -0
  87. package/src/v8/cli/schema/typeToSchema.ts +18 -1
  88. package/src/v8/cli/serve/server.ts +20 -55
  89. package/src/v8/cms.ts +226 -26
  90. package/src/v8/content.ts +30 -0
  91. package/src/v8/draft.ts +14 -10
  92. package/src/v8/hosts.ts +184 -0
  93. package/src/v8/index.ts +6 -8
  94. package/src/v8/remoteLoader.ts +17 -2
  95. package/src/v8/settings.ts +157 -0
  96. package/src/v8/telemetry.ts +43 -40
  97. package/src/v8/types.ts +48 -2
package/src/v8/index.ts CHANGED
@@ -1,16 +1,11 @@
1
1
  /**
2
2
  * The next-major (v8) core SDK: `createCMS`, the clients, the built-in blocks,
3
- * `matchRoute` and the draft helpers. Re-exported from the package root, where
3
+ * `matchRoute` and the draft pointer helpers (`cms.draftPointer` and
4
+ * `cms.draftCookie` are methods: they check the preview hosts). Re-exported from the package root, where
4
5
  * these names are the documented ones; see /next/api-reference.
5
6
  */
6
7
  export { createCMS, resetForTests } from "./cms.ts";
7
- export {
8
- DRAFT_COOKIE,
9
- draftCookie,
10
- draftPointer,
11
- formatDraftPointer,
12
- parseDraftPointer,
13
- } from "./draft.ts";
8
+ export { formatDraftPointer, parseDraftPointer } from "./draft.ts";
14
9
  export { matchRoute } from "./matchRoute.ts";
15
10
  export { remoteLoader } from "./remoteLoader.ts";
16
11
  export type {
@@ -21,13 +16,16 @@ export type {
21
16
  Client,
22
17
  CMS,
23
18
  CMSError,
19
+ CMSSettings,
24
20
  DraftPointer,
21
+ EffectiveSettings,
25
22
  Lazy,
26
23
  ListOptions,
27
24
  Loader,
28
25
  Match,
29
26
  Page,
30
27
  Redirect,
28
+ RequestLike,
31
29
  Result,
32
30
  Route,
33
31
  Secret,
@@ -39,7 +39,7 @@ import {
39
39
  DRAFT_OVERLAY_FORMAT,
40
40
  type DraftOverlay,
41
41
  } from "./canonical.ts";
42
- import { BoundedMap, isSnapshot } from "./content.ts";
42
+ import { BoundedMap, isSnapshot, PEEK_RELEASE, peekRelease } from "./content.ts";
43
43
  import { parseDraftPointer } from "./draft.ts";
44
44
  import { clearGlobals, contentIdentity, fnv1a } from "./identity.ts";
45
45
  import { isPlainObject } from "./json.ts";
@@ -92,6 +92,8 @@ class RemoteLoader implements Loader {
92
92
  readonly interval: number | undefined;
93
93
  #fallback: Snapshot | Loader;
94
94
  #fallbackRevision: string | undefined;
95
+ /** The fallback's content as last loaded, for a fallback that is itself a loader. */
96
+ #fallbackSnapshot: Snapshot | undefined;
95
97
  #current: Snapshot | undefined;
96
98
  #generation = -1;
97
99
  /** Authorized manifests, by overlay version and grant: a version alone unlocks nothing. */
@@ -115,6 +117,12 @@ class RemoteLoader implements Loader {
115
117
  if (fallback === this.#fallback) return;
116
118
  this.#fallback = fallback;
117
119
  this.#fallbackRevision = undefined;
120
+ this.#fallbackSnapshot = undefined;
121
+ }
122
+
123
+ /** What `load()` would return now, from memory only (see `peekRelease`). */
124
+ [PEEK_RELEASE](): Snapshot | undefined {
125
+ return this.#current ?? peekRelease(this.#fallback) ?? this.#fallbackSnapshot;
118
126
  }
119
127
 
120
128
  load(pointer?: string | null): Promise<Snapshot> {
@@ -153,7 +161,10 @@ class RemoteLoader implements Loader {
153
161
  async #loadFallback(): Promise<Snapshot> {
154
162
  const fallback = this.#fallback;
155
163
  const snapshot = isSnapshot(fallback) ? fallback : await (fallback as Loader).load();
156
- if (fallback === this.#fallback) this.#fallbackRevision = snapshot.revision;
164
+ if (fallback === this.#fallback) {
165
+ this.#fallbackRevision = snapshot.revision;
166
+ this.#fallbackSnapshot = snapshot;
167
+ }
157
168
  return snapshot;
158
169
  }
159
170
 
@@ -335,6 +346,10 @@ class LocalLoader implements Loader {
335
346
  this.#fallback = fallback;
336
347
  }
337
348
 
349
+ [PEEK_RELEASE](): Snapshot | undefined {
350
+ return peekRelease(this.#fallback);
351
+ }
352
+
338
353
  load(pointer?: string | null): Promise<Snapshot> {
339
354
  const fallback = this.#fallback;
340
355
  return isSnapshot(fallback) ? Promise.resolve(fallback) : fallback.load(pointer);
@@ -0,0 +1,157 @@
1
+ /**
2
+ * The CMS settings (see /next/built-in-blocks#cms-settings and
3
+ * /next/api-reference#cms-settings): the saved block `CMS`, of the built-in
4
+ * type `cms-settings`, read from the release, with the defaults filled in and
5
+ * code's caps applied.
6
+ *
7
+ * - The caller hands in the release snapshot already in memory; nothing here
8
+ * loads content, so reading settings never fetches.
9
+ * - A missing block, a block of another type, or a section that fails to
10
+ * resolve gives that section's defaults, still capped. Nothing rejects.
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.
15
+ */
16
+ import {
17
+ analyticsSection,
18
+ SETTINGS_BLOCK,
19
+ SETTINGS_TYPE,
20
+ telemetrySection,
21
+ } from "./builtins/data.ts";
22
+ import {
23
+ EVERY_HOST,
24
+ formatHostPattern,
25
+ type HostPattern,
26
+ parseHostPattern,
27
+ patternWithin,
28
+ } from "./hosts.ts";
29
+ import { isPlainObject } from "./json.ts";
30
+ import type { Client, CMSConfig, EffectiveSettings, Snapshot } from "./types.ts";
31
+
32
+ /** What code allows: the caps every section's content is held to. */
33
+ export interface SettingsCaps {
34
+ /** Code's `preview.hosts`, parsed; `undefined` when code sets none. */
35
+ hosts: readonly HostPattern[] | undefined;
36
+ limits: { errorSampleRate: number; traceSampleRate: number };
37
+ }
38
+
39
+ const SECTIONS = ["preview", "telemetry", "analytics"] as const;
40
+
41
+ /**
42
+ * Code's `preview.hosts`, parsed. Throws a `TypeError` on anything that isn't
43
+ * a list of host patterns: that's a bug in the app, not in content.
44
+ */
45
+ export function parseCodeHosts(preview: CMSConfig["preview"]): HostPattern[] | undefined {
46
+ if (preview === undefined || preview === null) return undefined;
47
+ if (typeof preview !== "object") {
48
+ throw new TypeError("createCMS: `preview` must be an object, such as { hosts: [...] }");
49
+ }
50
+ const { hosts } = preview;
51
+ if (hosts === undefined) return undefined;
52
+ if (!Array.isArray(hosts)) {
53
+ throw new TypeError("createCMS: `preview.hosts` must be a list of host patterns");
54
+ }
55
+ return hosts.map((raw) => {
56
+ const pattern = parseHostPattern(raw);
57
+ if (pattern === null) {
58
+ throw new TypeError(
59
+ `createCMS: ${JSON.stringify(raw)} in preview.hosts isn't a host pattern ` +
60
+ "(see /next/api-reference#host-patterns)",
61
+ );
62
+ }
63
+ return pattern;
64
+ });
65
+ }
66
+
67
+ /** The settings with nothing saved: every default, capped. */
68
+ export function defaultSettings(caps: SettingsCaps): EffectiveSettings {
69
+ return effectiveSettings({}, caps);
70
+ }
71
+
72
+ /**
73
+ * The settings a release holds. `client` reads that same release; it resolves
74
+ * the `CMS` block whole and, if that fails, each section on its own, so one
75
+ * failing section falls back to its defaults alone.
76
+ */
77
+ export async function readSettings(
78
+ snapshot: Snapshot | undefined,
79
+ client: () => Client,
80
+ caps: SettingsCaps,
81
+ ): Promise<EffectiveSettings> {
82
+ try {
83
+ const entry = snapshot?.blocks[SETTINGS_BLOCK];
84
+ if (!isPlainObject(entry) || entry.__resolveType !== SETTINGS_TYPE) {
85
+ return defaultSettings(caps);
86
+ }
87
+ const reader = client();
88
+ const [whole] = await reader.resolve<Record<string, unknown>>(SETTINGS_BLOCK);
89
+ if (isPlainObject(whole)) return effectiveSettings(whole, caps);
90
+ const sections: Record<string, unknown> = {};
91
+ await Promise.all(
92
+ SECTIONS.map(async (name) => {
93
+ if (entry[name] === undefined) return;
94
+ const [value] = await reader.resolve(entry[name]);
95
+ sections[name] = value ?? undefined; // a section that fails gets its defaults
96
+ }),
97
+ );
98
+ return effectiveSettings(sections, caps);
99
+ } catch {
100
+ return defaultSettings(caps);
101
+ }
102
+ }
103
+
104
+ /** Whether a saved block holds nothing to run, so its settings are the same on every call. */
105
+ export function isStatic(entry: Record<string, unknown>): boolean {
106
+ return Object.entries(entry).every(
107
+ ([key, value]) => key === "__resolveType" || !holdsBlock(value),
108
+ );
109
+ }
110
+
111
+ function holdsBlock(value: unknown): boolean {
112
+ if (Array.isArray(value)) return value.some(holdsBlock);
113
+ if (!isPlainObject(value)) return false;
114
+ return "__resolveType" in value || Object.values(value).some(holdsBlock);
115
+ }
116
+
117
+ /**
118
+ * The settings, deep-frozen: one object per release is handed to every caller,
119
+ * so a caller that writes to it would change it for every request.
120
+ */
121
+ function effectiveSettings(value: Record<string, unknown>, caps: SettingsCaps): EffectiveSettings {
122
+ const telemetry = telemetrySection(value.telemetry);
123
+ return deepFreeze({
124
+ preview: { hosts: effectiveHosts(value.preview, caps.hosts) },
125
+ telemetry: {
126
+ ...telemetry,
127
+ errorSampleRate: Math.min(telemetry.errorSampleRate, caps.limits.errorSampleRate),
128
+ traceSampleRate: Math.min(telemetry.traceSampleRate, caps.limits.traceSampleRate),
129
+ },
130
+ analytics: analyticsSection(value.analytics),
131
+ });
132
+ }
133
+
134
+ function deepFreeze<T>(value: T): T {
135
+ if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
136
+ Object.freeze(value);
137
+ for (const child of Object.values(value)) deepFreeze(child);
138
+ }
139
+ return value;
140
+ }
141
+
142
+ function effectiveHosts(preview: unknown, code: readonly HostPattern[] | undefined): string[] {
143
+ const saved = isPlainObject(preview) && Array.isArray(preview.hosts) ? preview.hosts : undefined;
144
+ if (saved === undefined) return code ? unique(code.map(formatHostPattern)) : [EVERY_HOST];
145
+ const kept: string[] = [];
146
+ for (const raw of saved) {
147
+ const pattern = parseHostPattern(raw);
148
+ if (pattern === null) continue; // not a pattern: left out
149
+ if (code && !code.some((cap) => patternWithin(pattern, cap))) continue;
150
+ kept.push(formatHostPattern(pattern));
151
+ }
152
+ return unique(kept);
153
+ }
154
+
155
+ function unique(values: string[]): string[] {
156
+ return [...new Set(values)];
157
+ }
@@ -5,8 +5,10 @@
5
5
  * - **Where** comes from code: `createCMS({ telemetry })`, or the standard
6
6
  * `OTEL_EXPORTER_OTLP_ENDPOINT`/`OTEL_EXPORTER_OTLP_HEADERS` when it's left
7
7
  * out. `false` sends nothing.
8
- * - **How much** comes from content: the `Telemetry` saved block of the
9
- * release being served, capped by `telemetry.limits`.
8
+ * - **How much** comes from content: the `telemetry` section of the CMS
9
+ * settings (`cms.settings()`, the release's `CMS` block), capped by
10
+ * `telemetry.limits`. The CMS reads it outside any request, when the
11
+ * release changes and then at most once a minute.
10
12
  * - Metrics are aggregated in memory (delta histograms); error logs and traces
11
13
  * are sampled. Batches leave in the background (after the response on
12
14
  * Workers, on an unref'd timer elsewhere); a send that fails is retried
@@ -15,10 +17,10 @@
15
17
  * cookies or authorization values, and no value a secret block decrypted.
16
18
  */
17
19
  import { hasBackgroundHook, later, runInBackground } from "./background.ts";
20
+ import { rate, TELEMETRY_DEFAULTS } from "./builtins/data.ts";
18
21
  import { isResolutionError } from "./errors.ts";
19
22
  import { readEnv } from "./identity.ts";
20
- import { isPlainObject } from "./json.ts";
21
- import type { CMSError, Snapshot, TelemetryConfig } from "./types.ts";
23
+ import type { CMSError, Snapshot, Telemetry, TelemetryConfig } from "./types.ts";
22
24
 
23
25
  /** The hosted Deco CMS collector, for `telemetry: { site, token }`. */
24
26
  const HOSTED_TELEMETRY_ENDPOINT = "https://otel.decocms.com";
@@ -31,9 +33,20 @@ const MAX_SECRETS = 1_000;
31
33
  const RETRY_STATUSES = new Set([429, 502, 503, 504]);
32
34
  /** OpenTelemetry's recommended `http.*.request.duration` buckets, in seconds. */
33
35
  const BOUNDS = [0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10];
34
- const DEFAULTS = { enabled: true, metrics: true, errorSampleRate: 0.05, traceSampleRate: 0 };
35
36
  const DEFAULT_LIMITS = { errorSampleRate: 0.1, traceSampleRate: 0 };
36
37
 
38
+ /** The caps on content's sample rates: `telemetry.limits`, defaults 0.1 and 0. */
39
+ export function telemetryLimits(config: false | TelemetryConfig | undefined): {
40
+ errorSampleRate: number;
41
+ traceSampleRate: number;
42
+ } {
43
+ const limits = config ? config.limits : undefined;
44
+ return {
45
+ errorSampleRate: rate(limits?.errorSampleRate, DEFAULT_LIMITS.errorSampleRate),
46
+ traceSampleRate: rate(limits?.traceSampleRate, DEFAULT_LIMITS.traceSampleRate),
47
+ };
48
+ }
49
+
37
50
  type Attributes = Record<string, string | number | boolean | undefined>;
38
51
 
39
52
  interface Destination {
@@ -92,10 +105,7 @@ export function resolveDestination(
92
105
  const headers = parseKeyValues(readEnv("OTEL_EXPORTER_OTLP_HEADERS"));
93
106
  return { endpoint, headers, site, limits: DEFAULT_LIMITS };
94
107
  }
95
- const limits = {
96
- errorSampleRate: rate(config.limits?.errorSampleRate, DEFAULT_LIMITS.errorSampleRate),
97
- traceSampleRate: rate(config.limits?.traceSampleRate, DEFAULT_LIMITS.traceSampleRate),
98
- };
108
+ const limits = telemetryLimits(config);
99
109
  if ("endpoint" in config) {
100
110
  if (typeof config.endpoint !== "string" || !config.endpoint) return null;
101
111
  return { endpoint: config.endpoint, headers: { ...config.headers }, site, limits };
@@ -111,8 +121,7 @@ export function resolveDestination(
111
121
 
112
122
  export class TelemetryPipeline {
113
123
  readonly #destination: Destination;
114
- #settings = { ...DEFAULTS };
115
- #settingsRevision: string | undefined;
124
+ #settings: Required<Telemetry> = { ...TELEMETRY_DEFAULTS };
116
125
  #release: string | undefined;
117
126
  #histograms = new Map<string, Histogram>();
118
127
  #logs: LogRecord[] = [];
@@ -124,7 +133,7 @@ export class TelemetryPipeline {
124
133
 
125
134
  constructor(destination: Destination) {
126
135
  this.#destination = destination;
127
- this.#apply(undefined);
136
+ this.apply(TELEMETRY_DEFAULTS);
128
137
  }
129
138
 
130
139
  /** Never send `value`: it's replaced with `[redacted]` in every log, span and label. */
@@ -132,13 +141,29 @@ export class TelemetryPipeline {
132
141
  if (value.length > 0 && this.#secrets.size < MAX_SECRETS) this.#secrets.add(value);
133
142
  }
134
143
 
135
- /** The release being served: its revision labels batches and its `Telemetry` block sets the rates. */
144
+ /** The release being served: its revision labels batches. */
136
145
  useRelease(snapshot: Snapshot): void {
137
146
  this.#release = snapshot.revision;
138
- if (this.#settingsRevision === snapshot.revision) return;
139
- this.#settingsRevision = snapshot.revision;
140
- const entry = snapshot.blocks.Telemetry;
141
- this.#apply(isPlainObject(entry) && entry.__resolveType === "telemetry" ? entry : undefined);
147
+ }
148
+
149
+ /**
150
+ * The `telemetry` section to follow (from `cms.settings()`). Rates are
151
+ * capped by the destination's limits here too, whatever the caller passed.
152
+ */
153
+ apply(section: Telemetry): void {
154
+ const { limits } = this.#destination;
155
+ this.#settings = {
156
+ enabled: typeof section.enabled === "boolean" ? section.enabled : TELEMETRY_DEFAULTS.enabled,
157
+ metrics: typeof section.metrics === "boolean" ? section.metrics : TELEMETRY_DEFAULTS.metrics,
158
+ errorSampleRate: Math.min(
159
+ rate(section.errorSampleRate, TELEMETRY_DEFAULTS.errorSampleRate),
160
+ limits.errorSampleRate,
161
+ ),
162
+ traceSampleRate: Math.min(
163
+ rate(section.traceSampleRate, TELEMETRY_DEFAULTS.traceSampleRate),
164
+ limits.traceSampleRate,
165
+ ),
166
+ };
142
167
  }
143
168
 
144
169
  histogram(name: string, attributes: Attributes, seconds: number): void {
@@ -188,7 +213,7 @@ export class TelemetryPipeline {
188
213
  /**
189
214
  * The hooks one client reports through. The trace decision is made once per
190
215
  * client, on its first block, after its release is loaded, so the first
191
- * client of a release already uses that release's `Telemetry` block.
216
+ * client of a release already uses that release's `telemetry` section.
192
217
  */
193
218
  forClient(): ClientTelemetry {
194
219
  let decided = false;
@@ -340,22 +365,6 @@ export class TelemetryPipeline {
340
365
  return scrubText(out);
341
366
  }
342
367
 
343
- #apply(block: Record<string, unknown> | undefined): void {
344
- const { limits } = this.#destination;
345
- this.#settings = {
346
- enabled: typeof block?.enabled === "boolean" ? block.enabled : DEFAULTS.enabled,
347
- metrics: typeof block?.metrics === "boolean" ? block.metrics : DEFAULTS.metrics,
348
- errorSampleRate: Math.min(
349
- rate(block?.errorSampleRate, DEFAULTS.errorSampleRate),
350
- limits.errorSampleRate,
351
- ),
352
- traceSampleRate: Math.min(
353
- rate(block?.traceSampleRate, DEFAULTS.traceSampleRate),
354
- limits.traceSampleRate,
355
- ),
356
- };
357
- }
358
-
359
368
  #schedule(): void {
360
369
  if (this.#scheduled) return;
361
370
  this.#scheduled = true;
@@ -483,12 +492,6 @@ function randomHex(bytes: number): string {
483
492
  return Array.from(values, (b) => b.toString(16).padStart(2, "0")).join("");
484
493
  }
485
494
 
486
- function rate(value: unknown, fallback: number): number {
487
- return typeof value === "number" && Number.isFinite(value)
488
- ? Math.min(1, Math.max(0, value))
489
- : fallback;
490
- }
491
-
492
495
  /** `k1=v1,k2=v2` with URL-encoded values, the format of the OTEL_* environment variables. */
493
496
  function parseKeyValues(raw: string | undefined): Record<string, string> {
494
497
  const out: Record<string, string> = {};
package/src/v8/types.ts CHANGED
@@ -130,7 +130,28 @@ export interface Variant<T> {
130
130
  value: Lazy<T>;
131
131
  }
132
132
 
133
- /** The `Telemetry` saved block's type (built-in `telemetry`). */
133
+ /**
134
+ * The built-in `cms-settings` block's props: the type of the well-known saved
135
+ * block `CMS`. Every field is optional, and any field can have variants. Read
136
+ * it through `cms.settings()`, which fills in the defaults and applies code's
137
+ * caps (see /next/built-in-blocks#cms-settings).
138
+ */
139
+ export interface CMSSettings {
140
+ /** Host patterns previews are allowed on, within `createCMS`'s `preview.hosts`. */
141
+ preview?: { hosts?: string[] };
142
+ telemetry?: Telemetry;
143
+ analytics?: Analytics;
144
+ }
145
+
146
+ /** What `cms.settings()` returns: every section, defaults filled in, caps applied. */
147
+ export interface EffectiveSettings {
148
+ /** `["*"]` means every host; an empty list, none. */
149
+ preview: { hosts: string[] };
150
+ telemetry: Required<Telemetry>;
151
+ analytics: Required<Analytics>;
152
+ }
153
+
154
+ /** The `telemetry` section of the CMS settings. */
134
155
  export interface Telemetry {
135
156
  /** Default `true`; `false` switches telemetry off. */
136
157
  enabled?: boolean;
@@ -142,7 +163,7 @@ export interface Telemetry {
142
163
  traceSampleRate?: number;
143
164
  }
144
165
 
145
- /** The built-in `analytics` block's props. Separate from telemetry. */
166
+ /** The `analytics` section of the CMS settings, and `AnalyticsScript`'s props. */
146
167
  export interface Analytics {
147
168
  /** An endpoint that accepts the One Dollar Stats format; default: the hosted Deco CMS collector. */
148
169
  collector?: string;
@@ -150,6 +171,9 @@ export interface Analytics {
150
171
  enabled?: boolean;
151
172
  }
152
173
 
174
+ /** Anything with a `url` and `headers`: a fetch `Request`, a `NextRequest`, a framework wrapper. */
175
+ export type RequestLike = Request | { url: string; headers: { get(name: string): string | null } };
176
+
153
177
  // ---------------------------------------------------------------------------
154
178
  // Results and errors
155
179
  // ---------------------------------------------------------------------------
@@ -201,6 +225,11 @@ export interface CMSConfig {
201
225
  interval?: number;
202
226
  /** Where telemetry goes; see /next/telemetry. */
203
227
  telemetry?: false | TelemetryConfig;
228
+ /**
229
+ * The most content may allow previews on, in the host pattern format
230
+ * (/next/api-reference#host-patterns). Without it, content may allow any host.
231
+ */
232
+ preview?: { hosts?: string[] };
204
233
  /** The private key that decrypts `secret` blocks. */
205
234
  secrets?: { key?: string };
206
235
  /** Your site's ID, for hosted releases and drafts. */
@@ -250,4 +279,21 @@ export interface CMS {
250
279
  forRevision(revision: string): Client;
251
280
  /** Ask the content source for newer content now; never throws. */
252
281
  update(): Promise<{ updated: boolean }>;
282
+ /**
283
+ * The release's CMS settings (the saved block `CMS`), defaults filled in and
284
+ * code's caps applied. Reads the release already in memory, never a draft;
285
+ * never fetches, never rejects.
286
+ */
287
+ settings(): Promise<EffectiveSettings>;
288
+ /**
289
+ * The request's draft pointer: `?__draft=` first, then the `deco-draft`
290
+ * cookie. `null` when neither is present, for `?__draft=off`, and on a host
291
+ * outside `settings().preview.hosts`, where the request gets the release.
292
+ */
293
+ draftPointer(request: RequestLike): Promise<string | null>;
294
+ /**
295
+ * The `Set-Cookie` value that starts a preview (a valid `?__draft=` on an
296
+ * allowed host) or ends one (`?__draft=off`, on any host); `null` otherwise.
297
+ */
298
+ draftCookie(request: RequestLike): Promise<string | null>;
253
299
  }