@decocms/blocks 8.18.1 → 8.20.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 (31) hide show
  1. package/dist/v8/analytics/client.d.ts +10 -0
  2. package/dist/v8/analytics/client.d.ts.map +1 -1
  3. package/dist/v8/analytics/client.js +29 -3
  4. package/dist/v8/analytics/client.js.map +1 -1
  5. package/dist/v8/client.js +1 -11
  6. package/dist/v8/client.js.map +1 -1
  7. package/dist/v8/experiments.d.ts +20 -50
  8. package/dist/v8/experiments.d.ts.map +1 -1
  9. package/dist/v8/experiments.js +35 -189
  10. package/dist/v8/experiments.js.map +1 -1
  11. package/package.json +1 -1
  12. package/skills/deco-go-live/SKILL.md +1 -1
  13. package/skills/deco-go-live/references/qa-checklist-template.md +1 -1
  14. package/skills/deco-go-live/scripts/preflight.sh +2 -2
  15. package/skills/deco-nextjs-site/SKILL.md +1 -1
  16. package/skills/deco-nextjs-site/references/proxy-and-drafts.md +1 -1
  17. package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +1 -1
  18. package/skills/deco-storefront-caching/references/verification.md +1 -1
  19. package/skills/deco-storefront-caching/references/worker-page-cache.md +1 -1
  20. package/skills/deco-tanstack-site/references/worker-entry.md +1 -1
  21. package/skills/deco-v7-to-v8-migration/references/nextjs.md +1 -1
  22. package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +1 -1
  23. package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +5 -6
  24. package/skills/deco-variants/SKILL.md +3 -3
  25. package/skills/deco-variants/references/caching-variants.md +2 -5
  26. package/skills/deco-variants/references/experiments-and-campaigns.md +3 -3
  27. package/skills/deco-variants/references/multivariate.md +1 -1
  28. package/skills/deco-variants/references/v7-matchers.md +5 -17
  29. package/src/v8/analytics/client.ts +36 -1
  30. package/src/v8/client.ts +1 -12
  31. package/src/v8/experiments.ts +39 -209
@@ -14,11 +14,10 @@
14
14
  * storage in an app) and hands it to `cms.client({ visitor })`; the built-in
15
15
  * `split-traffic` calls `assign` with it.
16
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.
17
+ * A visitor is only its id, stored as is in the `deco_vid` cookie and written
18
+ * once, on a first visit. v7's `deco_segment` is neither read nor written:
19
+ * its stored decisions aren't honoured, and a visitor who has only it gets a
20
+ * new id.
22
21
  */
23
22
 
24
23
  import { newId, roll } from "./bucketing.ts";
@@ -29,26 +28,10 @@ export type Experiments = Record<string, number>;
29
28
  /** What a visitor got: each test's name and whether they are in it. */
30
29
  export type Assignments = Record<string, boolean>;
31
30
 
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
- */
31
+ /** Who is visiting: an id every assignment is computed from, and nothing else. */
37
32
  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
- */
33
+ /** 16 random bytes as 22 base64url characters, drawn once per visitor. */
43
34
  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
35
  }
53
36
 
54
37
  /** What `readVisitor` answers. */
@@ -56,9 +39,8 @@ export interface VisitorFromRequest {
56
39
  /** The request's visitor, or a new one when it had none. */
57
40
  visitor: Visitor;
58
41
  /**
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.
42
+ * The `Set-Cookie` line to send when the visitor had no id (a first
43
+ * visit); `null` otherwise. Never send it from a preview.
62
44
  */
63
45
  cookie: string | null;
64
46
  }
@@ -69,161 +51,47 @@ interface RequestWithHeaders {
69
51
  headers: { get(name: string): string | null };
70
52
  }
71
53
 
72
- /** The visitor's stored form, v7's name for it. */
73
- const VISITOR_COOKIE = "deco_segment";
54
+ /** The visitor's cookie: the id, as is. */
55
+ const VISITOR_COOKIE = "deco_vid";
74
56
 
75
57
  /** One year: the id is the visitor, and it should outlive any single test. */
76
58
  const VISITOR_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
77
59
 
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
60
  const ID_RE = /^[A-Za-z0-9_-]{22}$/;
86
61
 
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;
62
+ /** The id in a stored value, or `undefined`. Tolerates surrounding spaces and percent-encoding. */
63
+ function idOf(text: string | null | undefined): string | undefined {
64
+ if (typeof text !== "string") return undefined;
65
+ let value = text.trim();
134
66
  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;
67
+ value = decodeURIComponent(value);
147
68
  } catch {
148
- return null;
69
+ return undefined;
149
70
  }
71
+ return ID_RE.test(value) ? value : undefined;
150
72
  }
151
73
 
152
- /** A new visitor: a fresh id and nothing else. */
74
+ /** A new visitor: a fresh id. */
153
75
  export function newVisitor(): Visitor {
154
- return { id: newId(), active: [], inactiveDrawn: [], pct: record() };
76
+ return { id: newId() };
155
77
  }
156
78
 
157
79
  /**
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.
80
+ * A visitor out of its stored form (what `serializeVisitor` wrote: the value
81
+ * of the `deco_vid` cookie or of `x-deco-visitor`). `null` when the text is
82
+ * missing or isn't an id. Never throws.
162
83
  */
163
84
  export function parseVisitor(text: string | null | undefined): Visitor | null {
164
- const stored = parseStored(text);
165
- return stored?.id === undefined ? null : (stored as Visitor);
85
+ const id = idOf(text);
86
+ return id === undefined ? null : { id };
166
87
  }
167
88
 
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
- */
89
+ /** The visitor's stored form: its id. */
174
90
  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;
91
+ return visitor.id;
224
92
  }
225
93
 
226
- /** The raw `deco_segment` value out of a `Cookie` header. */
94
+ /** The raw `deco_vid` value out of a `Cookie` header. */
227
95
  function readCookie(cookies: string | null): string | undefined {
228
96
  if (!cookies) return undefined;
229
97
  for (const part of cookies.split(";")) {
@@ -246,11 +114,10 @@ function isPlainHttp(url: string | undefined): boolean {
246
114
  }
247
115
 
248
116
  /**
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.
117
+ * The web helper: the visitor out of a request's `deco_vid` cookie, and the
118
+ * `Set-Cookie` line to send back when it had none (a first visit). The cookie
119
+ * isn't `HttpOnly`, so a script on the page can read the id, and is `Secure`
120
+ * unless the request came over plain http. Never throws.
254
121
  */
255
122
  export function readVisitor(request: RequestWithHeaders): VisitorFromRequest {
256
123
  let header: string | null = null;
@@ -259,9 +126,9 @@ export function readVisitor(request: RequestWithHeaders): VisitorFromRequest {
259
126
  } catch {
260
127
  header = null;
261
128
  }
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() };
129
+ const stored = parseVisitor(readCookie(header));
130
+ if (stored !== null) return { visitor: stored, cookie: null };
131
+ const visitor = newVisitor();
265
132
  const parts = [
266
133
  `${VISITOR_COOKIE}=${serializeVisitor(visitor)}`,
267
134
  "Path=/",
@@ -276,65 +143,28 @@ function roundPct(allocation: number): number {
276
143
  return Math.round(Math.min(100, Math.max(0, allocation)));
277
144
  }
278
145
 
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
146
  /**
292
147
  * This visitor's answer for every test: `true` when they are in it.
293
148
  *
294
149
  * A visitor is in a test when their roll for it (a fixed number in [0, 100)
295
150
  * from the test's name and their id) is under its percentage, so 0 puts
296
151
  * 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.
152
+ * fractional percentage is rounded. Without a visitor, or with an id that
153
+ * isn't 22 base64url characters, every test is `false`. Entries that aren't
154
+ * finite numbers are left out. Pure; never throws.
305
155
  */
306
156
  export function assign(
307
157
  experiments: Experiments | null | undefined,
308
158
  visitor: Visitor | null | undefined,
309
159
  ): Assignments {
310
- const assignments = record<boolean>();
160
+ const assignments = Object.create(null) as Assignments;
311
161
  if (typeof experiments !== "object" || experiments === null) return assignments;
312
162
  const id = visitor !== null && typeof visitor === "object" ? visitor.id : undefined;
313
163
  const known = typeof id === "string" && ID_RE.test(id);
314
- const v: Partial<Visitor> = visitor !== null && typeof visitor === "object" ? visitor : {};
315
164
  for (const name of Object.keys(experiments).sort()) {
316
165
  const allocation = experiments[name];
317
166
  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);
167
+ assignments[name] = known && roll(name, id as string) < roundPct(allocation);
330
168
  }
331
169
  return assignments;
332
170
  }
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
- }