@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,98 @@
1
+ /**
2
+ * `currentClient()`: the client whose resolve is running a block function.
3
+ *
4
+ * The inputs of a request (the visitor, the version) arrive as arguments to
5
+ * `cms.client()`; this only hands that client to the functions it runs, so a
6
+ * rule or a section can resolve other blocks through it (`experiments`,
7
+ * `campaigns`) and read `client.visitor`, `client.version` and `client.date`.
8
+ *
9
+ * The resolver sets the client while it calls a block function, so every
10
+ * runtime has it at the start of the function, before any `await`. Where an
11
+ * `AsyncLocalStorage` exists (the `#async-store` import picks it by
12
+ * condition, so this module imports no Node built-in) it also survives
13
+ * `await`. The slot lives on `globalThis` under a `Symbol.for` key, so two
14
+ * copies of the package share it, like the CMS instances.
15
+ */
16
+ import { createAsyncStore } from "#async-store";
17
+ import type { AsyncStore } from "../async/types.ts";
18
+ import type { Client } from "./types.ts";
19
+
20
+ const SLOT = Symbol.for("decocms.blocks.currentClient");
21
+
22
+ /** What a client was given, test or campaign name → on or off. */
23
+ export type Overrides = Readonly<Record<string, boolean>>;
24
+
25
+ /**
26
+ * The tests a client was given (`cms.client({ experiments })`): read by the
27
+ * built-in `split-traffic`. `Symbol.for`, so a second copy of the package
28
+ * reads it too.
29
+ */
30
+ export const EXPERIMENT_OVERRIDES: unique symbol = Symbol.for("decocms.blocks.experimentOverrides");
31
+
32
+ /**
33
+ * The campaigns a client was given (`cms.client({ campaigns })`): read by the
34
+ * built-in `calendar`. `Symbol.for`, like `EXPERIMENT_OVERRIDES`.
35
+ */
36
+ export const CAMPAIGN_OVERRIDES: unique symbol = Symbol.for("decocms.blocks.campaignOverrides");
37
+
38
+ interface Slot {
39
+ /** Set while a block function runs synchronously. */
40
+ active: Client | undefined;
41
+ /** Carries the client across `await`, where the runtime has one. */
42
+ store: AsyncStore<Client> | undefined;
43
+ }
44
+
45
+ function slot(): Slot {
46
+ const global = globalThis as unknown as Record<symbol, Slot | undefined>;
47
+ let current = global[SLOT];
48
+ if (current === undefined || typeof current !== "object") {
49
+ current = { active: undefined, store: createAsyncStore<Client>() };
50
+ global[SLOT] = current;
51
+ }
52
+ return current;
53
+ }
54
+
55
+ /**
56
+ * The client resolving the block function that calls it. Call it at the
57
+ * start of the function: without `AsyncLocalStorage` (browsers, React
58
+ * Native) it is only there before the function's first `await`. Throws
59
+ * outside a block function.
60
+ */
61
+ export function currentClient(): Client {
62
+ const { active, store } = slot();
63
+ const client = active ?? store?.getStore();
64
+ if (client === undefined) {
65
+ throw new Error(
66
+ "currentClient() was called outside a block function, or after an await where the " +
67
+ "runtime has no AsyncLocalStorage: call it at the start of the function, before any await",
68
+ );
69
+ }
70
+ return client;
71
+ }
72
+
73
+ /** Runs `fn` with `client` as the current client (the resolver calls each block function this way). */
74
+ export function runWithClient<R>(client: Client, fn: () => R): R {
75
+ const current = slot();
76
+ const previous = current.active;
77
+ current.active = client;
78
+ try {
79
+ return current.store === undefined ? fn() : current.store.run(client, fn);
80
+ } finally {
81
+ current.active = previous;
82
+ }
83
+ }
84
+
85
+ /** The tests a client was given, by name; `undefined` when none. */
86
+ export function experimentOverrides(client: Client): Overrides | undefined {
87
+ return overridesAt(client, EXPERIMENT_OVERRIDES);
88
+ }
89
+
90
+ /** The campaigns a client was given, by name; `undefined` when none. */
91
+ export function campaignOverrides(client: Client): Overrides | undefined {
92
+ return overridesAt(client, CAMPAIGN_OVERRIDES);
93
+ }
94
+
95
+ function overridesAt(client: Client, key: symbol): Overrides | undefined {
96
+ const value = (client as unknown as Record<symbol, unknown>)[key];
97
+ return typeof value === "object" && value !== null ? (value as Overrides) : undefined;
98
+ }
package/src/v8/draft.ts CHANGED
@@ -1,15 +1,30 @@
1
1
  /**
2
2
  * Draft pointers (see /next/api-reference#draft-pointers): the string
3
3
  * `<host[:port]><path[?query]>@<version>` that names a draft, and what
4
- * `cms.draftPointer` and `cms.draftCookie` read and write to carry one from a
5
- * `?__draft=` link into a cookie. The host check against the preview hosts is
6
- * the CMS's: these read the request only.
4
+ * `cms.readVersion` and `cms.draftCookie` read and write to carry one (or a
5
+ * published release's commit SHA) from a `?__draft=` link into a cookie. The
6
+ * host check against the preview hosts is the CMS's: these read the request
7
+ * only.
7
8
  *
8
- * The query's reserved `__variant` parameters are the variants a preview
9
- * forces (`<block>@<path>=<index>`, URL-encoded, one per multivariate); the
10
- * parser lifts them out of `path` into `variants`.
9
+ * A version is a draft pointer or a release's commit SHA, nothing else. A
10
+ * pointer's query may force variants, which are part of the draft it names:
11
+ *
12
+ * - `__variant=<block>@<path>=<index>`: a variant the preview forces, one per
13
+ * multivariate (`variants`).
14
+ *
15
+ * A Studio preview link carries more than the version: the moment it shows
16
+ * and the tests and campaigns it switches on or off. They ride in the same
17
+ * query (a pointer's, or after a SHA: `<sha>?__at=…&__test=…`), and
18
+ * `parseVersion` lifts them out into the client's other options:
19
+ *
20
+ * - `__at=<ISO date-time with offset>`: the client's `date`.
21
+ * - `__test=<name>=on|off`: a test in the client's `experiments`.
22
+ * - `__campaign=<name>=on|off`: a campaign in the client's `campaigns`.
23
+ *
24
+ * Each value is URL-encoded.
11
25
  */
12
- import type { DraftPointer, ForcedVariant, RequestLike } from "./types.ts";
26
+ import type { Assignments } from "./experiments.ts";
27
+ import type { DraftPointer, ForcedVariant, RequestLike, RequestVersion } from "./types.ts";
13
28
 
14
29
  /** The draft cookie's name. Not exported from the package: reading it directly would skip the host check. */
15
30
  const DRAFT_COOKIE = "__deco_draft";
@@ -26,13 +41,108 @@ const VERSION_RE = /^[A-Za-z0-9._-]{1,64}$/;
26
41
  const PATH_RE = /^\/[A-Za-z0-9/_.%~=&?-]*$/;
27
42
  const MAX_POINTER_LENGTH = 4096;
28
43
  const VARIANT_PARAM = "__variant=";
44
+ const AT_PARAM = "__at=";
45
+ const TEST_PARAM = "__test=";
46
+ const CAMPAIGN_PARAM = "__campaign=";
47
+ /** The parameters of a preview link that aren't part of the version. */
48
+ const PREVIEW_PARAMS = [AT_PARAM, TEST_PARAM, CAMPAIGN_PARAM];
49
+ /** An ISO 8601 date-time with its offset (`Z` or `±hh:mm`): the moment a preview shows. */
50
+ const AT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})$/;
29
51
  const INDEX_RE = /^(0|[1-9][0-9]{0,3})$/;
52
+ /** A published release: its git commit SHA (SHA-1, 40 lowercase hex). */
53
+ const REVISION_RE = /^[0-9a-f]{40}$/;
54
+
55
+ /** A version, read: a published release (by its commit SHA) or a draft. */
56
+ type ClientVersion = { kind: "revision"; sha: string } | { kind: "draft"; pointer: DraftPointer };
57
+
58
+ /**
59
+ * What `cms.client({ version })` reads: a published release's commit SHA (40
60
+ * lowercase hex, nothing after it) or a draft pointer. `null` for anything
61
+ * else, a preview link's `__at`, `__test` or `__campaign` included: those
62
+ * are the client's `date`, `experiments` and `campaigns` (`parseVersion`).
63
+ */
64
+ export function parseClientVersion(value: string): ClientVersion | null {
65
+ if (REVISION_RE.test(value)) return { kind: "revision", sha: value };
66
+ const pointer = parseDraftPointer(value);
67
+ return pointer === null ? null : { kind: "draft", pointer };
68
+ }
69
+
70
+ /**
71
+ * A Studio link's value (what `?__draft=` and the draft cookie carry): the
72
+ * version, a draft pointer or a published release's commit SHA, and the
73
+ * preview's moment and switched tests and campaigns, lifted out of its query
74
+ * as the client's `date`, `experiments` and `campaigns`. `null` for a value
75
+ * that is neither, or whose preview parameters don't parse (a second `__at`,
76
+ * a state other than `on` or `off`). The last `__test` or `__campaign` for a
77
+ * name wins. Spread it into `cms.client()`.
78
+ */
79
+ export function parseVersion(value: string | null | undefined): RequestVersion | null {
80
+ if (typeof value !== "string" || value.length === 0 || value.length > MAX_POINTER_LENGTH) {
81
+ return null;
82
+ }
83
+ const head = value.indexOf("?");
84
+ if (REVISION_RE.test(head === -1 ? value : value.slice(0, head))) {
85
+ if (head === -1) return { version: value };
86
+ const preview = liftPreview(value.slice(head + 1));
87
+ // After a SHA, only the preview's own parameters.
88
+ if (preview === null || preview.kept.length > 0) return null;
89
+ return { version: value.slice(0, head), ...preview.options };
90
+ }
91
+ const at = value.lastIndexOf("@");
92
+ if (at <= 0) return null;
93
+ const location = value.slice(0, at);
94
+ const q = location.indexOf("?");
95
+ if (q === -1) return parseDraftPointer(value) === null ? null : { version: value };
96
+ const preview = liftPreview(location.slice(q + 1));
97
+ if (preview === null) return null;
98
+ const query = preview.kept.length === 0 ? "" : `?${preview.kept.join("&")}`;
99
+ const version = `${location.slice(0, q)}${query}${value.slice(at)}`;
100
+ return parseDraftPointer(version) === null ? null : { version, ...preview.options };
101
+ }
102
+
103
+ /** A query's preview parameters, read, and the other parameters, kept as they are. */
104
+ function liftPreview(query: string): {
105
+ kept: string[];
106
+ options: Omit<RequestVersion, "version">;
107
+ } | null {
108
+ const kept: string[] = [];
109
+ let at: string | undefined;
110
+ let experiments: Assignments | undefined;
111
+ let campaigns: Assignments | undefined;
112
+ for (const param of query.split("&")) {
113
+ if (param.startsWith(AT_PARAM)) {
114
+ const value = decodeParam(param.slice(AT_PARAM.length));
115
+ if (at !== undefined || value === null || !AT_RE.test(value)) return null;
116
+ if (Number.isNaN(Date.parse(value))) return null;
117
+ at = value;
118
+ } else if (param.startsWith(TEST_PARAM)) {
119
+ const test = decodeSwitch(param.slice(TEST_PARAM.length));
120
+ if (test === null) return null;
121
+ experiments ??= Object.create(null) as Assignments;
122
+ experiments[test.name] = test.on;
123
+ } else if (param.startsWith(CAMPAIGN_PARAM)) {
124
+ const campaign = decodeSwitch(param.slice(CAMPAIGN_PARAM.length));
125
+ if (campaign === null) return null;
126
+ campaigns ??= Object.create(null) as Assignments;
127
+ campaigns[campaign.name] = campaign.on;
128
+ } else if (param !== "") {
129
+ kept.push(param);
130
+ }
131
+ }
132
+ const options: Omit<RequestVersion, "version"> = {};
133
+ if (at !== undefined) options.date = new Date(Date.parse(at));
134
+ if (experiments !== undefined) options.experiments = experiments;
135
+ if (campaigns !== undefined) options.campaigns = campaigns;
136
+ return { kept, options };
137
+ }
30
138
 
31
139
  /**
32
140
  * Parses a pointer, strictly: `null` on a scheme, a stray `@`, an unrooted
33
- * path, an odd character in the host or version, or a port out of range. The
34
- * host is lowercased (DNS names are case-insensitive); path and version are
35
- * kept as they are.
141
+ * path, an odd character in the host or version, a port out of range, or a
142
+ * preview link's `__at`, `__test` or `__campaign` left in its query (they
143
+ * aren't part of a version: `parseVersion` lifts them out). The host is
144
+ * lowercased (DNS names are case-insensitive); path and version are kept as
145
+ * they are.
36
146
  */
37
147
  export function parseDraftPointer(raw: string | null | undefined): DraftPointer | null {
38
148
  if (typeof raw !== "string" || raw.length === 0 || raw.length > MAX_POINTER_LENGTH) return null;
@@ -51,9 +161,9 @@ export function parseDraftPointer(raw: string | null | undefined): DraftPointer
51
161
  if (host === null) return null;
52
162
  const split = splitVariants(path);
53
163
  if (split === null) return null;
54
- return split.variants.length === 0
55
- ? { host, path, version }
56
- : { host, path: split.path, version, variants: split.variants };
164
+ const pointer: DraftPointer = { host, path: split.path, version };
165
+ if (split.variants.length > 0) pointer.variants = split.variants;
166
+ return pointer;
57
167
  }
58
168
 
59
169
  /**
@@ -80,25 +190,49 @@ export function formatDraftPointer(pointer: DraftPointer): string {
80
190
  return `${parsed.host}${path}@${parsed.version}`;
81
191
  }
82
192
 
83
- /** The path without its `__variant` parameters, and the variants they force; `null` on a bad one. */
193
+ /**
194
+ * The path without its `__variant` parameters, and the variants they force.
195
+ * `null` on one that doesn't parse, or on a preview link's `__at`, `__test`
196
+ * or `__campaign`.
197
+ */
84
198
  function splitVariants(path: string): { path: string; variants: ForcedVariant[] } | null {
85
199
  const q = path.indexOf("?");
86
200
  if (q === -1) return { path, variants: [] };
87
201
  const kept: string[] = [];
88
202
  const variants: ForcedVariant[] = [];
89
203
  for (const param of path.slice(q + 1).split("&")) {
90
- if (!param.startsWith(VARIANT_PARAM)) {
204
+ if (param.startsWith(VARIANT_PARAM)) {
205
+ const variant = decodeVariant(param.slice(VARIANT_PARAM.length));
206
+ if (variant === null) return null;
207
+ variants.push(variant);
208
+ } else if (PREVIEW_PARAMS.some((prefix) => param.startsWith(prefix))) {
209
+ return null;
210
+ } else {
91
211
  kept.push(param);
92
- continue;
93
212
  }
94
- const variant = decodeVariant(param.slice(VARIANT_PARAM.length));
95
- if (variant === null) return null;
96
- variants.push(variant);
97
213
  }
98
214
  const base = path.slice(0, q);
99
215
  return { path: kept.length === 0 ? base : `${base}?${kept.join("&")}`, variants };
100
216
  }
101
217
 
218
+ /** `<name>=on|off`: the state after the last `=`, the test's or campaign's name before it. */
219
+ function decodeSwitch(encoded: string): { name: string; on: boolean } | null {
220
+ const raw = decodeParam(encoded);
221
+ if (raw === null) return null;
222
+ const eq = raw.lastIndexOf("=");
223
+ const state = raw.slice(eq + 1);
224
+ if (eq <= 0 || (state !== "on" && state !== "off")) return null;
225
+ return { name: raw.slice(0, eq), on: state === "on" };
226
+ }
227
+
228
+ function decodeParam(encoded: string): string | null {
229
+ try {
230
+ return decodeURIComponent(encoded);
231
+ } catch {
232
+ return null;
233
+ }
234
+ }
235
+
102
236
  /** `<block>@<path>=<index>`: the index after the last `=`, the block before the last `@`. */
103
237
  function decodeVariant(encoded: string): ForcedVariant | null {
104
238
  let raw: string;
@@ -117,8 +251,12 @@ function decodeVariant(encoded: string): ForcedVariant | null {
117
251
  }
118
252
 
119
253
  function encodeVariant({ block, path, index }: ForcedVariant): string {
254
+ return encodeParam(`${block}@${path}=${index}`);
255
+ }
256
+
257
+ function encodeParam(value: string): string {
120
258
  // encodeURIComponent leaves !'()* as they are; the pointer's path doesn't allow them.
121
- return encodeURIComponent(`${block}@${path}=${index}`).replace(
259
+ return encodeURIComponent(value).replace(
122
260
  /[!'()*]/g,
123
261
  (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
124
262
  );
@@ -157,23 +295,25 @@ function normalizeIPv6Host(authority: string): string | null {
157
295
  }
158
296
 
159
297
  /**
160
- * The draft pointer a request carries: `?__draft=` from the URL first, then
161
- * the `__deco_draft` cookie. `null` when neither is present, or when the URL
162
- * says `?__draft=off`. A value that doesn't parse is ignored, as if it were
298
+ * The version a request carries (a draft pointer, or a published release's
299
+ * commit SHA) with its preview's date, tests and campaigns (`parseVersion`):
300
+ * `?__draft=` from the URL first, then the `__deco_draft`
301
+ * cookie. `null` when neither is present, or when the URL says
302
+ * `?__draft=off`. A value that doesn't parse is ignored, as if it were
163
303
  * absent: a stray `?__draft=junk` link or a mangled cookie gets the release,
164
- * never an error from `cms.forDraft`.
304
+ * never an error from `cms.client`.
165
305
  */
166
- export function readDraftPointer(request: RequestLike): string | null {
306
+ export function readVersion(request: RequestLike): RequestVersion | null {
167
307
  const param = draftParam(request);
168
308
  if (param === DRAFT_OFF) return null;
169
- if (param && parseDraftPointer(param) !== null) return param;
170
- const cookie = readCookie(request.headers.get("cookie"), DRAFT_COOKIE);
171
- return cookie && parseDraftPointer(cookie) !== null ? cookie : null;
309
+ const fromLink = param ? parseVersion(param) : null;
310
+ if (fromLink !== null) return fromLink;
311
+ return parseVersion(readCookie(request.headers.get("cookie"), DRAFT_COOKIE));
172
312
  }
173
313
 
174
314
  /**
175
315
  * The `Set-Cookie` value for a request whose URL carries `?__draft=`: one that
176
- * stores the pointer, or one that expires the cookie when the value is `off`
316
+ * stores the version (a draft pointer or a release's commit SHA), or one that expires the cookie when the value is `off`
177
317
  * (how the site editor ends a preview). `null` on every other request, and for
178
318
  * a pointer that doesn't parse, so garbage never lands in the cookie.
179
319
  *
@@ -185,7 +325,7 @@ export function draftCookieFor(request: RequestLike): string | null {
185
325
  const param = draftParam(request);
186
326
  if (!param) return null;
187
327
  if (param === DRAFT_OFF) return serializeCookie("", ["Max-Age=0"]);
188
- if (parseDraftPointer(param) === null) return null;
328
+ if (parseVersion(param) === null) return null;
189
329
  return serializeCookie(encodeURIComponent(param), []);
190
330
  }
191
331