@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.
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
@@ -0,0 +1,340 @@
1
+ /**
2
+ * `@decocms/blocks/experiments`: who is in which A/B test, decided the same
3
+ * way on a server, in a browser and in a mobile app.
4
+ *
5
+ * The percentages are content (the saved block `experiments`, of the built-in
6
+ * type `split-traffic`); a decision is arithmetic over the visitor's id. What
7
+ * a visitor gets is never stored: it is recomputed from the percentage and the
8
+ * id, so one id serves every test (each roll hashes `name:id`), a new test
9
+ * needs no new state and two tests are independent.
10
+ *
11
+ * Pure functions over values and strings: no React, no framework, no module
12
+ * state, no environment reads, no network. Nothing here is called for you:
13
+ * the app reads the visitor its own way (`readVisitor` on the web, device
14
+ * storage in an app) and hands it to `cms.client({ visitor })`; the built-in
15
+ * `split-traffic` calls `assign` with it.
16
+ *
17
+ * The stored form is v7's `deco_segment` (the same fields and encoding; names
18
+ * sorted by code unit rather than v7's `localeCompare`) plus an `id`, so a
19
+ * visitor carried over from v7 keeps the group v7 put them in and analytics
20
+ * keeps reading the cookie it already reads. A visitor is written once, when
21
+ * it has no id; v7's stored assignments are read and honoured, never rewritten.
22
+ */
23
+
24
+ import { newId, roll } from "./bucketing.ts";
25
+
26
+ /** The saved block `experiments`: each test's name and the whole percentage of visitors in it, 0–100. */
27
+ export type Experiments = Record<string, number>;
28
+
29
+ /** What a visitor got: each test's name and whether they are in it. */
30
+ export type Assignments = Record<string, boolean>;
31
+
32
+ /**
33
+ * Who is visiting: an id every assignment is computed from, plus the
34
+ * assignments v7 stored (`active`, `inactiveDrawn`, `pct`, `exp`), which are honoured and
35
+ * carried, never rewritten.
36
+ */
37
+ export interface Visitor {
38
+ /**
39
+ * 16 random bytes as 22 base64url characters, drawn once per visitor. `""`
40
+ * for a visitor with no id of its own (one built from a cache key's
41
+ * assignments), which is in only the tests `active` names.
42
+ */
43
+ id: string;
44
+ /** Tests v7 put this visitor in. */
45
+ active: string[];
46
+ /** Tests v7 left this visitor out of. */
47
+ inactiveDrawn: string[];
48
+ /** The percentage each of v7's decisions was made at. */
49
+ pct: Record<string, number>;
50
+ /** v7's N-way decisions. Never read; carried as they are. */
51
+ exp?: Record<string, string>;
52
+ }
53
+
54
+ /** What `readVisitor` answers. */
55
+ export interface VisitorFromRequest {
56
+ /** The request's visitor, or a new one when it had none. */
57
+ visitor: Visitor;
58
+ /**
59
+ * The `Set-Cookie` line to send when the visitor had no id (a first visit,
60
+ * or a v7 visitor getting theirs); `null` otherwise. Never send it from a
61
+ * preview.
62
+ */
63
+ cookie: string | null;
64
+ }
65
+
66
+ /** The fields of a request `readVisitor` reads: a `Request`, or anything with its `headers`. */
67
+ interface RequestWithHeaders {
68
+ url?: string;
69
+ headers: { get(name: string): string | null };
70
+ }
71
+
72
+ /** The visitor's stored form, v7's name for it. */
73
+ const VISITOR_COOKIE = "deco_segment";
74
+
75
+ /** One year: the id is the visitor, and it should outlive any single test. */
76
+ const VISITOR_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
77
+
78
+ /**
79
+ * A cookie over this stays out of every request. An id plus 50 of v7's
80
+ * decisions fits well under it; past it, `serializeVisitor` drops entries,
81
+ * the ones the id reproduces first.
82
+ */
83
+ const COOKIE_BUDGET = 2048;
84
+
85
+ const ID_RE = /^[A-Za-z0-9_-]{22}$/;
86
+
87
+ /** A stored visitor before it is known to have an id. */
88
+ type Stored = Omit<Visitor, "id"> & { id?: string };
89
+
90
+ /**
91
+ * A record with no prototype, so a name such as `__proto__` is an ordinary
92
+ * key: decided, written and read back like any other.
93
+ */
94
+ function record<T>(): Record<string, T> {
95
+ return Object.create(null) as Record<string, T>;
96
+ }
97
+
98
+ function emptyStored(): Stored {
99
+ return { active: [], inactiveDrawn: [], pct: record() };
100
+ }
101
+
102
+ function stringList(value: unknown): string[] {
103
+ if (!Array.isArray(value)) return [];
104
+ return value.filter((entry): entry is string => typeof entry === "string");
105
+ }
106
+
107
+ function pctRecord(value: unknown): Record<string, number> {
108
+ const out = record<number>();
109
+ if (typeof value !== "object" || value === null) return out;
110
+ for (const [name, pct] of Object.entries(value as Record<string, unknown>)) {
111
+ if (typeof pct === "number" && Number.isFinite(pct)) out[name] = pct;
112
+ }
113
+ return out;
114
+ }
115
+
116
+ function expRecord(value: unknown): Record<string, string> | undefined {
117
+ if (typeof value !== "object" || value === null) return undefined;
118
+ const out = record<string>();
119
+ for (const [name, variant] of Object.entries(value as Record<string, unknown>)) {
120
+ if (typeof variant === "string") out[name] = variant;
121
+ }
122
+ return Object.keys(out).length > 0 ? out : undefined;
123
+ }
124
+
125
+ /**
126
+ * A stored value, with or without an id; `null` when it doesn't read. Never
127
+ * throws. The value may arrive percent-encoded (some cookie APIs encode what
128
+ * they write; base64 never holds a `%`, so decoding first is always safe).
129
+ * Entries of the wrong type are dropped, and an id that is not 22 base64url
130
+ * characters is treated as absent.
131
+ */
132
+ function parseStored(text: string | null | undefined): Stored | null {
133
+ if (typeof text !== "string" || text === "") return null;
134
+ try {
135
+ const parsed: unknown = JSON.parse(decodeURIComponent(atob(decodeURIComponent(text.trim()))));
136
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
137
+ const body = parsed as Record<string, unknown>;
138
+ const stored: Stored = {
139
+ active: stringList(body.active),
140
+ inactiveDrawn: stringList(body.inactiveDrawn),
141
+ pct: pctRecord(body.pct),
142
+ };
143
+ if (typeof body.id === "string" && ID_RE.test(body.id)) stored.id = body.id;
144
+ const exp = expRecord(body.exp);
145
+ if (exp) stored.exp = exp;
146
+ return stored;
147
+ } catch {
148
+ return null;
149
+ }
150
+ }
151
+
152
+ /** A new visitor: a fresh id and nothing else. */
153
+ export function newVisitor(): Visitor {
154
+ return { id: newId(), active: [], inactiveDrawn: [], pct: record() };
155
+ }
156
+
157
+ /**
158
+ * A visitor out of its stored form (what `serializeVisitor` wrote, the value
159
+ * of the `deco_segment` cookie). `null` when the text is missing, doesn't
160
+ * read, or holds no id (a v7 value: `readVisitor` gives it one, keeping its
161
+ * decisions). Never throws.
162
+ */
163
+ export function parseVisitor(text: string | null | undefined): Visitor | null {
164
+ const stored = parseStored(text);
165
+ return stored?.id === undefined ? null : (stored as Visitor);
166
+ }
167
+
168
+ /**
169
+ * The visitor's stored form: v7's `btoa(encodeURIComponent(JSON.stringify(...)))`,
170
+ * with a fixed key order and names sorted, so two equal visitors give
171
+ * byte-equal values. Under 2KB: past it, v7's entries are dropped, first the
172
+ * ones the id reproduces anyway.
173
+ */
174
+ export function serializeVisitor(visitor: Visitor): string {
175
+ const active = [...visitor.active].sort();
176
+ const inactiveDrawn = [...visitor.inactiveDrawn].sort();
177
+ const dropped = new Set<string>();
178
+
179
+ const encode = (): string => {
180
+ const stillActive = active.filter((name) => !dropped.has(name));
181
+ const stillInactive = inactiveDrawn.filter((name) => !dropped.has(name));
182
+ const pct = record<number>();
183
+ for (const name of Object.keys(visitor.pct).sort()) {
184
+ // v7 kept a `pct` beside its N-way names too, and `exp` is carried
185
+ // untouched, so their fingerprint is carried with it.
186
+ const listed =
187
+ stillActive.includes(name) ||
188
+ stillInactive.includes(name) ||
189
+ (visitor.exp !== undefined && Object.hasOwn(visitor.exp, name));
190
+ if (listed) pct[name] = visitor.pct[name] as number;
191
+ }
192
+ const body: Record<string, unknown> = {
193
+ active: stillActive,
194
+ inactiveDrawn: stillInactive,
195
+ pct,
196
+ };
197
+ if (visitor.id !== undefined) body.id = visitor.id;
198
+ if (visitor.exp !== undefined) body.exp = visitor.exp;
199
+ return btoa(encodeURIComponent(JSON.stringify(body)));
200
+ };
201
+
202
+ let value = encode();
203
+ if (value.length <= COOKIE_BUDGET) return value;
204
+
205
+ // Over budget. A dropped entry is decided by the roll from then on, which
206
+ // keeps the decision only when the stored one already agrees with the roll.
207
+ // So drop those first, and the others only if the value is still too big.
208
+ const reproducible = (name: string): boolean => {
209
+ const pct = visitor.pct[name];
210
+ if (typeof pct !== "number") return false;
211
+ return active.includes(name) === roll(name, visitor.id) < pct;
212
+ };
213
+ for (const name of [
214
+ ...inactiveDrawn.filter(reproducible),
215
+ ...active.filter(reproducible),
216
+ ...inactiveDrawn.filter((name) => !reproducible(name)),
217
+ ...active.filter((name) => !reproducible(name)),
218
+ ]) {
219
+ if (value.length <= COOKIE_BUDGET) break;
220
+ dropped.add(name);
221
+ value = encode();
222
+ }
223
+ return value;
224
+ }
225
+
226
+ /** The raw `deco_segment` value out of a `Cookie` header. */
227
+ function readCookie(cookies: string | null): string | undefined {
228
+ if (!cookies) return undefined;
229
+ for (const part of cookies.split(";")) {
230
+ const eq = part.indexOf("=");
231
+ if (eq < 0) continue;
232
+ if (part.slice(0, eq).trim() !== VISITOR_COOKIE) continue;
233
+ return part.slice(eq + 1).trim();
234
+ }
235
+ return undefined;
236
+ }
237
+
238
+ /** Whether a request came over plain http (localhost), where a `Secure` cookie isn't stored. */
239
+ function isPlainHttp(url: string | undefined): boolean {
240
+ if (typeof url !== "string") return false;
241
+ try {
242
+ return new URL(url).protocol === "http:";
243
+ } catch {
244
+ return false;
245
+ }
246
+ }
247
+
248
+ /**
249
+ * The web helper: the visitor out of a request's `deco_segment` cookie, and
250
+ * the `Set-Cookie` line to send back when it had no id (a first visit, or a
251
+ * v7 visitor, whose decisions are kept). The cookie isn't `HttpOnly` (the
252
+ * analytics script reads it, as in v7) and is `Secure` unless the request
253
+ * came over plain http. Never throws.
254
+ */
255
+ export function readVisitor(request: RequestWithHeaders): VisitorFromRequest {
256
+ let header: string | null = null;
257
+ try {
258
+ header = request.headers.get("cookie");
259
+ } catch {
260
+ header = null;
261
+ }
262
+ const stored = parseStored(readCookie(header));
263
+ if (stored?.id !== undefined) return { visitor: stored as Visitor, cookie: null };
264
+ const visitor: Visitor = { ...(stored ?? emptyStored()), id: newId() };
265
+ const parts = [
266
+ `${VISITOR_COOKIE}=${serializeVisitor(visitor)}`,
267
+ "Path=/",
268
+ `Max-Age=${VISITOR_COOKIE_MAX_AGE}`,
269
+ "SameSite=Lax",
270
+ ];
271
+ if (!isPlainHttp(request.url)) parts.push("Secure");
272
+ return { visitor, cookie: parts.join("; ") };
273
+ }
274
+
275
+ function roundPct(allocation: number): number {
276
+ return Math.round(Math.min(100, Math.max(0, allocation)));
277
+ }
278
+
279
+ /**
280
+ * A v7 decision after the percentage moved: raising a percentage never
281
+ * removes anyone v7 put in, and lowering it never adds anyone v7 left out.
282
+ * Otherwise the roll decides, as for any visitor.
283
+ */
284
+ function keptFromV7(stored: boolean, from: number, to: number): boolean | undefined {
285
+ if (to === from) return stored;
286
+ if (stored && to > from) return true;
287
+ if (!stored && to < from) return false;
288
+ return undefined;
289
+ }
290
+
291
+ /**
292
+ * This visitor's answer for every test: `true` when they are in it.
293
+ *
294
+ * A visitor is in a test when their roll for it (a fixed number in [0, 100)
295
+ * from the test's name and their id) is under its percentage, so 0 puts
296
+ * nobody in, 100 everybody, and raising a percentage only adds people. A
297
+ * fractional percentage is rounded. An assignment v7 stored is honoured while
298
+ * the percentage it was made at holds (a missing or `-1` percentage, v7's
299
+ * "any", included); once it moves, a v7 visitor in a test that grows stays
300
+ * in and one out of a test that shrinks stays out. Without a visitor every
301
+ * test is `false`. A visitor without an id (`""`, as a page built from a
302
+ * cache key's assignments gives one) has no roll: it is in exactly the tests
303
+ * its stored `active` and `pct` keep it in. Entries that aren't finite numbers are
304
+ * left out. Pure; never throws.
305
+ */
306
+ export function assign(
307
+ experiments: Experiments | null | undefined,
308
+ visitor: Visitor | null | undefined,
309
+ ): Assignments {
310
+ const assignments = record<boolean>();
311
+ if (typeof experiments !== "object" || experiments === null) return assignments;
312
+ const id = visitor !== null && typeof visitor === "object" ? visitor.id : undefined;
313
+ const known = typeof id === "string" && ID_RE.test(id);
314
+ const v: Partial<Visitor> = visitor !== null && typeof visitor === "object" ? visitor : {};
315
+ for (const name of Object.keys(experiments).sort()) {
316
+ const allocation = experiments[name];
317
+ if (typeof allocation !== "number" || !Number.isFinite(allocation)) continue;
318
+ const pct = roundPct(allocation);
319
+ const stored = list(v.active).includes(name)
320
+ ? true
321
+ : list(v.inactiveDrawn).includes(name)
322
+ ? false
323
+ : undefined;
324
+ // v7 wrote `round(traffic * 100)` here, and its own reader treated a
325
+ // missing or negative entry as "matches anything".
326
+ const raw = isRecord(v.pct) && Object.hasOwn(v.pct, name) ? v.pct[name] : undefined;
327
+ const from = typeof raw === "number" && Number.isFinite(raw) && raw >= 0 ? roundPct(raw) : pct;
328
+ const kept = stored === undefined ? undefined : keptFromV7(stored, from, pct);
329
+ assignments[name] = kept ?? (known && roll(name, id as string) < pct);
330
+ }
331
+ return assignments;
332
+ }
333
+
334
+ function list(value: unknown): string[] {
335
+ return Array.isArray(value) ? value : [];
336
+ }
337
+
338
+ function isRecord(value: unknown): value is Record<string, unknown> {
339
+ return typeof value === "object" && value !== null;
340
+ }
package/src/v8/hosts.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  /**
2
- * Host patterns (see /next/api-reference#host-patterns): the format of
3
- * `preview.hosts`, in `createCMS` and in the `CMS` block.
2
+ * Host patterns (see /next/api-reference#host-patterns): the format of a
3
+ * release's `previewHosts` (Studio writes them into the release metadata)
4
+ * and of `createCMS`'s `preview.hosts`.
4
5
  *
5
6
  * - Hostnames and patterns are compared lowercase, with one trailing dot
6
7
  * removed; names outside ASCII in their punycode form.
package/src/v8/index.ts CHANGED
@@ -1,11 +1,13 @@
1
1
  /**
2
- * The next-major (v8) core SDK: `createCMS`, the clients, the built-in blocks,
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
2
+ * The next-major (v8) core SDK: `createCMS`, the clients, `currentClient`,
3
+ * the built-in blocks, `matchRoute` and the draft pointer helpers
4
+ * (`cms.readVersion` and `cms.draftCookie` are methods: they check the
5
+ * preview hosts). Re-exported from the package root, where
5
6
  * these names are the documented ones; see /next/api-reference.
6
7
  */
7
8
  export { createCMS, resetForTests } from "./cms.ts";
8
- export { formatDraftPointer, parseDraftPointer } from "./draft.ts";
9
+ export { currentClient } from "./current.ts";
10
+ export { formatDraftPointer, parseDraftPointer, parseVersion } from "./draft.ts";
9
11
  export { matchRoute } from "./matchRoute.ts";
10
12
  export { remoteLoader } from "./remoteLoader.ts";
11
13
  export type {
@@ -14,6 +16,7 @@ export type {
14
16
  BlockFunction,
15
17
  Blocks,
16
18
  Client,
19
+ ClientOptions,
17
20
  CMS,
18
21
  CMSError,
19
22
  CMSSettings,
@@ -26,6 +29,7 @@ export type {
26
29
  Page,
27
30
  Redirect,
28
31
  RequestLike,
32
+ RequestVersion,
29
33
  Result,
30
34
  Route,
31
35
  Secret,
@@ -9,13 +9,13 @@
9
9
  * across restarts: every boot starts from the fallback.
10
10
  * - `update()` (the CMS calls it in the background, on first use and then
11
11
  * every interval) reads `sites/<site>/latest.json`,
12
- * `{ revision, schemaHash, publishedAt }`. Whoever is newer wins: when it
12
+ * `{ revision, schemaHash, publishedAt, previewHosts }`. Whoever is newer wins: when it
13
13
  * names a revision other than the one this process last swapped in, its
14
14
  * `schemaHash` equals the fallback's, and its `publishedAt` is later than
15
15
  * the fallback's `committedAt` (the commit time of the git HEAD
16
16
  * `deco content` built it from), it downloads
17
- * `sites/<site>/revisions/<revision>.json`, `{ revision, schemaHash, blocks }`,
18
- * and swaps it in whole. Otherwise, and on any error, memory stays as it is.
17
+ * `sites/<site>/revisions/<revision>.json`,
18
+ * `{ revision, schemaHash, blocks, previewHosts }`, and swaps it in whole. Otherwise, and on any error, memory stays as it is.
19
19
  * A fallback without a `schemaHash` never swaps; one without a `committedAt`
20
20
  * (a custom loader, an older content module, a build outside git) counts as
21
21
  * the oldest. Studio writes `publishedAt` on Publish, on "Make current" (a
@@ -25,17 +25,49 @@
25
25
  * a publish still loses to it.
26
26
  * Pointers aren't ordered among themselves, and the fallback's content is
27
27
  * never compared: only the two timestamps are.
28
+ * - `previewHosts` (host patterns) is where the site may be previewed: Studio
29
+ * knows the site's addresses and writes them into the release metadata
30
+ * whenever it writes `latest.json` or a revision (delivery is trusted).
31
+ * Previews are checked against the current release's list: the last
32
+ * `latest.json` read, whether or not its revision was swapped in (a newer
33
+ * bundle still previews where Studio says). With no list to check
34
+ * (PO 2026-10-22), previews are allowed on every host: a site with no
35
+ * `latest.json` yet (a 404), or one whose `latest.json` has no
36
+ * `previewHosts` (published before Studio wrote the list; its next publish
37
+ * writes one). A read that fails (a network error, a 5xx, a malformed
38
+ * `latest.json`) isn't "no list": until a read succeeds, previews stay
39
+ * closed, and a later failure keeps the last answer (a 404 once a list
40
+ * was read is a failure too: a published site stays published).
41
+ * A preview request before this process has read `latest.json` reads it
42
+ * then (only `latest.json`, once, shared); a read older than the interval
43
+ * is read again the same way, so `dev: true` follows Studio too.
28
44
  * - With `dev: true`, it never swaps, so local files win. `createCMS` passes
29
45
  * its `dev` option, or `NODE_ENV === "development"` when the site omits it;
30
46
  * this loader reads no environment itself.
31
47
  * - A release larger than `MAX_SNAPSHOT_BYTES` is refused while it downloads,
32
48
  * before it's buffered whole (a Worker isolate has 128 MB).
49
+ * - A client can ask for a published release by its commit SHA
50
+ * (`cms.client({ version })`): it's read from
51
+ * `sites/<site>/revisions/<sha>.json` on first use and kept in memory, a
52
+ * few at a time (the least recently used dropped first), since a revision
53
+ * never changes. One built with another schema than the bundled content is
54
+ * an error, never half a page.
33
55
  * - Without `site` it's a plain loader over the fallback.
34
56
  *
35
57
  * Instances are process-wide singletons, like `createCMS`'s.
36
58
  */
37
59
  import { readBoundedJson, timeoutSignal } from "./boundedJson.ts";
38
- import { isSnapshot, PEEK_RELEASE, peekRelease } from "./content.ts";
60
+ import {
61
+ BoundedMap,
62
+ isSnapshot,
63
+ PEEK_RELEASE,
64
+ PREVIEW_HOSTS,
65
+ peekRelease,
66
+ previewHostsOf,
67
+ READ_REVISION,
68
+ type ReleasePreviewHosts,
69
+ } from "./content.ts";
70
+ import { errors } from "./errors.ts";
39
71
  import { clearGlobals, contentIdentity } from "./identity.ts";
40
72
  import { isPlainObject } from "./json.ts";
41
73
  import type { Loader, Snapshot } from "./types.ts";
@@ -49,9 +81,15 @@ const INSTANCE_PREFIX = "decocms.blocks.remote:";
49
81
  const FETCH_TIMEOUT_MS = 10_000;
50
82
  /** The largest release accepted, in bytes of JSON. */
51
83
  const MAX_SNAPSHOT_BYTES = 64 * 1024 * 1024;
84
+ /** Published releases kept in memory once read (a client asked for one by its SHA). */
85
+ const CACHED_REVISIONS = 3;
52
86
  // OPEN: a revision is the git commit SHA; only SHA-1 (40 hex) object names are accepted.
53
87
  const REVISION = /^[0-9a-f]{40}$/;
54
88
  const SCHEMA_HASH = /^[0-9a-f]{64}$/;
89
+ /** How long a failed read of the preview hosts waits before a preview request tries again. */
90
+ const PREVIEW_HOSTS_RETRY_MS = 10_000;
91
+ /** How old the preview hosts may get before a preview request reads them again (without `interval`). */
92
+ const PREVIEW_HOSTS_MAX_AGE_MS = 60_000;
55
93
 
56
94
  interface RemoteLoaderOptions {
57
95
  site?: string;
@@ -66,6 +104,15 @@ interface Latest {
66
104
  revision: string;
67
105
  schemaHash: string;
68
106
  publishedAt: string;
107
+ /** Where the site may be previewed; `undefined` when Studio wrote none. */
108
+ previewHosts: string[] | undefined;
109
+ }
110
+
111
+ /** A revision file's body. */
112
+ interface Revision {
113
+ blocks: Record<string, unknown>;
114
+ schemaHash: string;
115
+ previewHosts: string[] | undefined;
69
116
  }
70
117
 
71
118
  class RemoteLoader implements Loader {
@@ -78,6 +125,18 @@ class RemoteLoader implements Loader {
78
125
  /** The release this process last swapped in; `undefined` serves the fallback. */
79
126
  #current: Snapshot | undefined;
80
127
  readonly #dev: boolean;
128
+ /** Published releases read by SHA; immutable, so a hit is never revalidated. */
129
+ readonly #revisions = new BoundedMap<string, Promise<Snapshot>>(CACHED_REVISIONS);
130
+ /**
131
+ * The preview hosts the last read of `latest.json` found (its list, or
132
+ * `"every"`: a 404, or no `previewHosts` in it), and when. A failed read
133
+ * leaves it as it was.
134
+ */
135
+ #hosts: { list: readonly string[] | "every"; at: number } | undefined;
136
+ /** A read of `latest.json` for its preview hosts, in flight. */
137
+ #hostsRead: Promise<void> | undefined;
138
+ /** When that read last failed. */
139
+ #hostsFailedAt = Number.NEGATIVE_INFINITY;
81
140
 
82
141
  constructor(
83
142
  fallback: Snapshot | Loader,
@@ -118,13 +177,117 @@ class RemoteLoader implements Loader {
118
177
  // OPEN: a process that already swapped a release in keeps it (memory stays as it is).
119
178
  if (!isNewer(latest.publishedAt, fallback.committedAt)) return { updated: false };
120
179
  if (latest.revision === this.#current?.revision) return { updated: false };
121
- const blocks = await this.#revision(site, latest);
122
- const next: Snapshot = { revision: latest.revision, blocks, schemaHash: latest.schemaHash };
180
+ const revision = await this.#revision(site, latest);
181
+ const next: Snapshot = {
182
+ revision: latest.revision,
183
+ blocks: revision.blocks,
184
+ schemaHash: latest.schemaHash,
185
+ };
186
+ if (revision.previewHosts !== undefined) next.previewHosts = revision.previewHosts;
123
187
  if (fallback.aliases !== undefined) next.aliases = fallback.aliases;
124
188
  this.#current = next;
125
189
  return { updated: true };
126
190
  }
127
191
 
192
+ /**
193
+ * The current release's preview hosts (see `PREVIEW_HOSTS`): the last
194
+ * successful read of `latest.json`, reading it first when there is none yet
195
+ * or it is older than the interval (`peek`: never). `"every"` when
196
+ * the site has no `latest.json` (a 404) or it names no `previewHosts`;
197
+ * `"unknown"` while no read has succeeded (a failed one is retried after a
198
+ * pause), so previews stay closed rather than open on an error.
199
+ */
200
+ async [PREVIEW_HOSTS](peek = false): Promise<ReleasePreviewHosts> {
201
+ const known = this.#hosts;
202
+ const maxAge = this.interval ?? PREVIEW_HOSTS_MAX_AGE_MS;
203
+ const stale = known === undefined || Date.now() - known.at >= maxAge;
204
+ if (!peek && stale && Date.now() - this.#hostsFailedAt >= PREVIEW_HOSTS_RETRY_MS) {
205
+ this.#hostsRead ??= this.#latest(encodeURIComponent(this.#site))
206
+ .then(
207
+ () => undefined,
208
+ () => {
209
+ // A 404 is an answer (`#latest` recorded it), not a failure.
210
+ if (this.#hosts === known) this.#hostsFailedAt = Date.now();
211
+ },
212
+ )
213
+ .finally(() => {
214
+ this.#hostsRead = undefined;
215
+ });
216
+ await this.#hostsRead;
217
+ }
218
+ const list = this.#hosts?.list;
219
+ if (list === undefined) return "unknown";
220
+ return list === "every" ? list : list.slice();
221
+ }
222
+
223
+ /** A published release by its commit SHA (see `READ_REVISION`). */
224
+ async [READ_REVISION](sha: string): Promise<Snapshot> {
225
+ if (!REVISION.test(sha)) throw errors.loaderFailed(`"${sha}" is not a release's commit SHA`);
226
+ if (this.#current?.revision === sha) return this.#current;
227
+ const fallback = this.#fallbackSnapshot ?? (await this.#loadFallback());
228
+ if (fallback.revision === sha) return fallback;
229
+ if (fallback.schemaHash === undefined) {
230
+ throw errors.loaderFailed(
231
+ `the release ${sha} can't be checked against this code: the bundled content has no schemaHash (run deco content)`,
232
+ );
233
+ }
234
+ const snapshot = await this.#readRevision(sha);
235
+ if (snapshot.schemaHash !== fallback.schemaHash) {
236
+ throw errors.loaderFailed(
237
+ `the release ${sha} was published with another schema than this code's ` +
238
+ `(${snapshot.schemaHash} ≠ ${fallback.schemaHash}): preview it on a deploy of its own code`,
239
+ );
240
+ }
241
+ if (fallback.aliases === undefined) return snapshot;
242
+ return { ...snapshot, aliases: fallback.aliases };
243
+ }
244
+
245
+ /** Reads a revision once; a failed read isn't kept, so the next client tries again. */
246
+ #readRevision(sha: string): Promise<Snapshot> {
247
+ const held = this.#revisions.get(sha);
248
+ if (held !== undefined) return held;
249
+ const site = encodeURIComponent(this.#site);
250
+ const pending = this.#fetchRevision(site, sha, "the revision asked for").then((body) => {
251
+ const snapshot: Snapshot = {
252
+ revision: sha,
253
+ blocks: body.blocks,
254
+ schemaHash: body.schemaHash,
255
+ };
256
+ if (body.previewHosts !== undefined) snapshot.previewHosts = body.previewHosts;
257
+ return snapshot;
258
+ });
259
+ this.#revisions.set(sha, pending);
260
+ pending.catch(() => {
261
+ if (this.#revisions.get(sha) === pending) this.#revisions.delete(sha);
262
+ });
263
+ return pending;
264
+ }
265
+
266
+ async #fetchRevision(site: string, sha: string, expected: string): Promise<Revision> {
267
+ const label = `revision ${sha}`;
268
+ const response = await fetchWithTimeout(
269
+ `${deliveryOrigin()}/sites/${site}/revisions/${sha}.json`,
270
+ );
271
+ if (!response.ok) {
272
+ await response.body?.cancel();
273
+ throw new Error(`${label}: HTTP ${response.status}`);
274
+ }
275
+ const body = await readBoundedJson(response, label, MAX_SNAPSHOT_BYTES);
276
+ if (
277
+ !isPlainObject(body) ||
278
+ body.revision !== sha ||
279
+ typeof body.schemaHash !== "string" ||
280
+ !isPlainObject(body.blocks)
281
+ ) {
282
+ throw new Error(`${label}: unexpected format, or not ${expected}`);
283
+ }
284
+ return {
285
+ blocks: body.blocks,
286
+ schemaHash: body.schemaHash,
287
+ previewHosts: previewHostsOf(body.previewHosts),
288
+ };
289
+ }
290
+
128
291
  async #loadFallback(): Promise<Snapshot> {
129
292
  const fallback = this.#fallback;
130
293
  const snapshot = isSnapshot(fallback) ? fallback : await (fallback as Loader).load();
@@ -136,6 +299,12 @@ class RemoteLoader implements Loader {
136
299
  const response = await fetchWithTimeout(`${deliveryOrigin()}/sites/${site}/latest.json`);
137
300
  if (!response.ok) {
138
301
  await response.body?.cancel();
302
+ // Not published yet: no list, so previews are allowed on every host (PO 2026-10-22).
303
+ // A site this process has read a list for can't be unpublished: a 404 then
304
+ // (a CDN fault, a publish caught mid-write) is a failed read, so it keeps the list.
305
+ if (response.status === 404 && !Array.isArray(this.#hosts?.list)) {
306
+ this.#hosts = { list: "every", at: Date.now() };
307
+ }
139
308
  throw new Error(`latest.json: HTTP ${response.status}`);
140
309
  }
141
310
  const body: unknown = await response.json();
@@ -150,28 +319,24 @@ class RemoteLoader implements Loader {
150
319
  ) {
151
320
  throw new Error("latest.json: unexpected format");
152
321
  }
153
- return body as unknown as Latest;
322
+ const previewHosts = previewHostsOf(body.previewHosts);
323
+ // The current release's metadata, whether or not its revision is swapped in.
324
+ // No `previewHosts` (published before Studio wrote the list): every host, as with no latest.json.
325
+ this.#hosts = { list: previewHosts ?? "every", at: Date.now() };
326
+ return {
327
+ revision: body.revision,
328
+ schemaHash: body.schemaHash,
329
+ publishedAt: body.publishedAt,
330
+ previewHosts,
331
+ };
154
332
  }
155
333
 
156
- async #revision(site: string, latest: Latest): Promise<Record<string, unknown>> {
157
- const label = `revision ${latest.revision}`;
158
- const response = await fetchWithTimeout(
159
- `${deliveryOrigin()}/sites/${site}/revisions/${latest.revision}.json`,
160
- );
161
- if (!response.ok) {
162
- await response.body?.cancel();
163
- throw new Error(`${label}: HTTP ${response.status}`);
164
- }
165
- const body = await readBoundedJson(response, label, MAX_SNAPSHOT_BYTES);
166
- if (
167
- !isPlainObject(body) ||
168
- body.revision !== latest.revision ||
169
- body.schemaHash !== latest.schemaHash ||
170
- !isPlainObject(body.blocks)
171
- ) {
172
- throw new Error(`${label}: unexpected format, or not the revision latest.json names`);
334
+ async #revision(site: string, latest: Latest): Promise<Revision> {
335
+ const body = await this.#fetchRevision(site, latest.revision, "the revision latest.json names");
336
+ if (body.schemaHash !== latest.schemaHash) {
337
+ throw new Error(`revision ${latest.revision}: not the schema latest.json names`);
173
338
  }
174
- return body.blocks;
339
+ return body;
175
340
  }
176
341
  }
177
342