@decocms/blocks 8.5.2 → 8.7.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 (126) 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 +113 -44
  57. package/dist/v8/cms.js.map +1 -1
  58. package/dist/v8/content.d.ts +80 -1
  59. package/dist/v8/content.d.ts.map +1 -1
  60. package/dist/v8/content.js +149 -4
  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/preview/DraftBadge.d.ts +9 -1
  83. package/dist/v8/preview/DraftBadge.d.ts.map +1 -1
  84. package/dist/v8/preview/DraftBadge.js +42 -2
  85. package/dist/v8/preview/DraftBadge.js.map +1 -1
  86. package/dist/v8/remoteLoader.d.ts.map +1 -1
  87. package/dist/v8/remoteLoader.js +169 -21
  88. package/dist/v8/remoteLoader.js.map +1 -1
  89. package/dist/v8/resolver.d.ts +4 -2
  90. package/dist/v8/resolver.d.ts.map +1 -1
  91. package/dist/v8/resolver.js +11 -3
  92. package/dist/v8/resolver.js.map +1 -1
  93. package/dist/v8/settings.d.ts +16 -4
  94. package/dist/v8/settings.d.ts.map +1 -1
  95. package/dist/v8/settings.js +24 -21
  96. package/dist/v8/settings.js.map +1 -1
  97. package/dist/v8/types.d.ts +162 -22
  98. package/dist/v8/types.d.ts.map +1 -1
  99. package/package.json +35 -1
  100. package/src/async/default.ts +13 -0
  101. package/src/async/node.ts +12 -0
  102. package/src/async/types.ts +5 -0
  103. package/src/index.ts +4 -0
  104. package/src/v8/bucketing.ts +88 -0
  105. package/src/v8/builtins/campaigns.ts +120 -0
  106. package/src/v8/builtins/data.ts +2 -2
  107. package/src/v8/builtins/experiments.ts +72 -0
  108. package/src/v8/builtins/index.ts +7 -2
  109. package/src/v8/builtins/matchers.ts +0 -26
  110. package/src/v8/cli/builtins.ts +23 -0
  111. package/src/v8/cli/check/index.ts +289 -8
  112. package/src/v8/cli/schema/builtinSchemas.ts +82 -22
  113. package/src/v8/cli/schema/generate.ts +48 -3
  114. package/src/v8/client.ts +76 -10
  115. package/src/v8/cms.ts +134 -45
  116. package/src/v8/content.ts +168 -4
  117. package/src/v8/current.ts +98 -0
  118. package/src/v8/draft.ts +170 -30
  119. package/src/v8/experiments.ts +340 -0
  120. package/src/v8/hosts.ts +3 -2
  121. package/src/v8/index.ts +8 -4
  122. package/src/v8/preview/DraftBadge.tsx +72 -2
  123. package/src/v8/remoteLoader.ts +193 -26
  124. package/src/v8/resolver.ts +14 -4
  125. package/src/v8/settings.ts +35 -29
  126. package/src/v8/types.ts +163 -20
@@ -1,5 +1,5 @@
1
1
  /**
2
- * The forms of the nine built-in blocks (spec: built-in-blocks, and the types
2
+ * The forms of the twelve built-in blocks (spec: built-in-blocks, and the types
3
3
  * in api-reference › Types). They're always in the schema, unless the block
4
4
  * map declares the same key, which replaces the built-in.
5
5
  */
@@ -12,11 +12,14 @@ export const BUILT_IN_GROUPS: Record<string, ManifestGroup> = {
12
12
  multivariate: "loaders",
13
13
  always: "matchers",
14
14
  never: "matchers",
15
- date: "matchers",
15
+ experiment: "matchers",
16
+ campaign: "matchers",
16
17
  page: "pages",
17
18
  redirect: "redirects",
18
19
  "cms-settings": "content",
19
20
  secret: "loaders",
21
+ "split-traffic": "content",
22
+ calendar: "content",
20
23
  };
21
24
 
22
25
  const BUILT_IN_DOCS: Record<string, { title: string; description: string; icon?: string }> = {
@@ -28,21 +31,69 @@ const BUILT_IN_DOCS: Record<string, { title: string; description: string; icon?:
28
31
  },
29
32
  always: { title: "Always", description: "Always true: the fallback variant", icon: "eye" },
30
33
  never: { title: "Never", description: "Always false: hides a block", icon: "eye-off" },
31
- date: {
32
- title: "Date and time",
33
- description: "True from start until end",
34
+ experiment: {
35
+ title: "A/B test",
36
+ description: "True for the visitors in a test of the saved block experiments",
37
+ icon: "flask",
38
+ },
39
+ campaign: {
40
+ title: "Campaign",
41
+ description: "True while a campaign of the saved block campaigns is running",
34
42
  icon: "calendar-event",
35
43
  },
36
44
  page: { title: "Page", description: "A page at a URL" },
37
45
  redirect: { title: "Redirect", description: "Sends one URL to another" },
38
46
  "cms-settings": {
39
47
  title: "CMS settings",
40
- description: "Preview hosts, telemetry and analytics: the saved block named CMS",
48
+ description: "Telemetry and analytics: the saved block named CMS",
41
49
  icon: "settings",
42
50
  },
51
+ "split-traffic": {
52
+ title: "Split traffic",
53
+ description:
54
+ "A/B tests: each name with the percentage of visitors in it (0 off, 100 everyone); resolves to whether the visitor is in each. The type of the saved block experiments",
55
+ icon: "flask",
56
+ },
57
+ calendar: {
58
+ title: "Calendar",
59
+ description:
60
+ "Campaigns: each name with its start and end; resolves to whether each is running now. The type of the saved block campaigns",
61
+ icon: "calendar-event",
62
+ },
43
63
  secret: { title: "Secret", description: "An encrypted value, decrypted on the server" },
44
64
  };
45
65
 
66
+ /** The form of each test in a `split-traffic` block: a whole percentage. */
67
+ const ALLOCATION = {
68
+ type: "integer",
69
+ title: "Visitors in (%)",
70
+ description: "0 turns the test off, 100 shows it to everyone",
71
+ minimum: 0,
72
+ maximum: 100,
73
+ };
74
+
75
+ /** The form of each campaign in a `calendar` block: one window, both bounds optional. */
76
+ const CAMPAIGN_DATES = {
77
+ type: "object",
78
+ title: "Campaign dates",
79
+ properties: {
80
+ start: {
81
+ type: "string",
82
+ format: "date-time",
83
+ title: "Start",
84
+ description:
85
+ "The campaign runs from this moment on: a date and time with your store's offset (empty: since always)",
86
+ },
87
+ end: {
88
+ type: "string",
89
+ format: "date-time",
90
+ title: "End",
91
+ description:
92
+ "The campaign stops at this moment: a date and time with your store's offset (empty: never)",
93
+ },
94
+ },
95
+ };
96
+
46
97
  function resolveTypeProperty(key: string) {
47
98
  return { type: "string", enum: [key], default: key };
48
99
  }
@@ -114,14 +165,34 @@ function builtInProps(name: string, ctx: BuiltInContext): any {
114
165
  case "always":
115
166
  case "never":
116
167
  return { type: "object", properties: {} };
117
- case "date":
168
+ case "experiment":
169
+ return {
170
+ type: "object",
171
+ required: ["name"],
172
+ properties: {
173
+ name: {
174
+ type: "string",
175
+ title: "Test",
176
+ description: "A test in the saved block experiments",
177
+ },
178
+ },
179
+ };
180
+ case "campaign":
118
181
  return {
119
182
  type: "object",
183
+ required: ["name"],
120
184
  properties: {
121
- start: { type: "string", format: "date-time", title: "Start" },
122
- end: { type: "string", format: "date-time", title: "End" },
185
+ name: {
186
+ type: "string",
187
+ title: "Campaign",
188
+ description: "A campaign in the saved block campaigns",
189
+ },
123
190
  },
124
191
  };
192
+ case "split-traffic":
193
+ case "calendar":
194
+ // The names are the content: every key but __resolveType is one (see builtInDefinition).
195
+ return { type: "object", properties: {} };
125
196
  case "page":
126
197
  return {
127
198
  type: "object",
@@ -163,19 +234,6 @@ function builtInProps(name: string, ctx: BuiltInContext): any {
163
234
  return {
164
235
  type: "object",
165
236
  properties: {
166
- preview: {
167
- type: "object",
168
- title: "Preview",
169
- properties: {
170
- hosts: {
171
- type: "array",
172
- title: "Hosts",
173
- description:
174
- "Host patterns drafts may be previewed on, such as staging.example.com or *.example.com; empty turns previews off. Without it, every host (or the hosts code allows).",
175
- items: { type: "string" },
176
- },
177
- },
178
- },
179
237
  telemetry: {
180
238
  type: "object",
181
239
  title: "Telemetry",
@@ -239,6 +297,8 @@ export function builtInDefinition(name: string, ctx: BuiltInContext): any {
239
297
  return flatDefinition(name, builtInProps(name, ctx), {
240
298
  description: docs.description,
241
299
  ...(docs.icon ? { icon: docs.icon } : {}),
300
+ ...(name === "split-traffic" ? { additionalProperties: ALLOCATION } : {}),
301
+ ...(name === "calendar" ? { additionalProperties: CAMPAIGN_DATES } : {}),
242
302
  });
243
303
  }
244
304
 
@@ -103,9 +103,23 @@ interface BlockInfo {
103
103
 
104
104
  const BUILT_IN_TYPES_SOURCE = `
105
105
  export interface Seo { title: string; description: string }
106
+ export interface SeoFields { title?: string; description?: string }
106
107
  export interface Route { name: string; path: string }
108
+ export interface NameStates { [name: string]: boolean }
107
109
  `;
108
110
 
111
+ /**
112
+ * Built-in blocks a field can take, by the interface in BUILT_IN_TYPES_SOURCE
113
+ * their value has: `split-traffic` and `calendar` resolve to name →
114
+ * true/false, so a field typed `Assignments` (or any `Record<string,
115
+ * boolean>`) can hold the saved `experiments` or `campaigns` block. A block
116
+ * map that declares the name replaces it.
117
+ */
118
+ const BUILT_IN_RETURNS: Record<string, string> = {
119
+ "split-traffic": "NameStates",
120
+ calendar: "NameStates",
121
+ };
122
+
109
123
  /** The package version, written into the schema's `version`. */
110
124
 
111
125
  function siteName(root: string): string {
@@ -177,6 +191,7 @@ export async function generateSchema(paths: DecoPaths): Promise<SchemaResult> {
177
191
  });
178
192
  const builtInTypes = project.sourceFile(builtInTypesFile);
179
193
  const seoType = builtInTypes.getInterfaceType("Seo");
194
+ const seoFieldsType = builtInTypes.getInterfaceType("SeoFields");
180
195
  const routeType = builtInTypes.getInterfaceType("Route");
181
196
  const source = project.sourceFile(blockMap);
182
197
  const diagnostics: SchemaDiagnostic[] = [];
@@ -269,8 +284,15 @@ export async function generateSchema(paths: DecoPaths): Promise<SchemaResult> {
269
284
  // -------------------------------------------------------------------------
270
285
  // 2. Fields → blocks: which functions' return types fit an object field.
271
286
  // -------------------------------------------------------------------------
272
- const STRUCTURAL = new Set<string>(["lazy", "multivariate", "secret", "always", "never", "date"]);
273
- const candidates = infos.filter(
287
+ const STRUCTURAL = new Set<string>([
288
+ "lazy",
289
+ "multivariate",
290
+ "secret",
291
+ "always",
292
+ "never",
293
+ "campaign",
294
+ ]);
295
+ const candidates: Pick<BlockInfo, "key" | "returnType">[] = infos.filter(
274
296
  (info) =>
275
297
  info.group !== "sections" &&
276
298
  info.group !== "matchers" &&
@@ -279,6 +301,10 @@ export async function generateSchema(paths: DecoPaths): Promise<SchemaResult> {
279
301
  !info.returnType.isUnknown() &&
280
302
  !nonNullable(info.returnType).isNever(),
281
303
  );
304
+ for (const [key, typeName] of Object.entries(BUILT_IN_RETURNS)) {
305
+ if (infos.some((info) => info.key === key)) continue;
306
+ candidates.push({ key, returnType: builtInTypes.getInterfaceType(typeName) });
307
+ }
282
308
  const fitCache = new Map<unknown, string[]>();
283
309
  const definitions: Record<string, any> = {};
284
310
 
@@ -380,7 +406,12 @@ export async function generateSchema(paths: DecoPaths): Promise<SchemaResult> {
380
406
  };
381
407
  }
382
408
 
383
- const seoRefs = ctx.fitting(seoType).map((key) => ({ $ref: `#/definitions/${key}` }));
409
+ // The page's seo field: blocks that return a Seo, or only optional SEO
410
+ // fields of their own (a migrated site's PageSeo); loaders of content that
411
+ // happens to carry a title stay out.
412
+ const seoRefs = candidates
413
+ .filter((c) => returnFits(c.returnType, seoType) || hasSeoFields(c.returnType, seoFieldsType))
414
+ .map((c) => ({ $ref: `#/definitions/${toBase64(c.key)}` }));
384
415
  for (const name of BUILT_IN_BLOCKS) {
385
416
  if (declared.has(name)) continue;
386
417
  const group = BUILT_IN_GROUPS[name];
@@ -465,6 +496,20 @@ function sameNamedType(a: Type, b: Type): boolean {
465
496
  return sa !== undefined && sa === sb;
466
497
  }
467
498
 
499
+ /**
500
+ * Whether a block returns SEO fields of its own: an object (not a list) whose
501
+ * every property is optional, such as a migrated site's PageSeo, with a
502
+ * `title` or a `description`, each a string when set. A loader whose result
503
+ * has required fields (a blog post's `title` and `excerpt`, a category's
504
+ * `name`) is content, not SEO, and stays out.
505
+ */
506
+ function hasSeoFields(returnType: Type, seoFields: Type): boolean {
507
+ const source = nonNullable(returnType);
508
+ if (source.isArray() || !source.isObject() || !isWeakType(source)) return false;
509
+ if (!source.getProperty("title") && !source.getProperty("description")) return false;
510
+ return source.isAssignableTo(seoFields);
511
+ }
512
+
468
513
  /**
469
514
  * Does a function returning `returnType` fit a field of type `field`? The
470
515
  * TypeScript rule (assignability of the awaited, non-null types), except for
package/src/v8/client.ts CHANGED
@@ -1,8 +1,12 @@
1
1
  /**
2
2
  * A client: one revision, loaded on first use and read for the rest of its
3
- * life, plus a memo of block results. Create one per request.
3
+ * life, plus a memo of block results, and the inputs it was created with
4
+ * (the version, the visitor, the date, the tests and campaigns it was given).
5
+ * Create one per request.
4
6
  */
7
+ import { CAMPAIGN_OVERRIDES, EXPERIMENT_OVERRIDES, type Overrides } from "./current.ts";
5
8
  import { errors, isResolutionError, ResolutionError } from "./errors.ts";
9
+ import type { Visitor } from "./experiments.ts";
6
10
  import { isBlock } from "./json.ts";
7
11
  import { Resolver } from "./resolver.ts";
8
12
  import type { ClientTelemetry } from "./telemetry.ts";
@@ -23,6 +27,16 @@ interface ClientOptions {
23
27
  blocks: Blocks;
24
28
  /** The built-ins, with this CMS's `secret`. */
25
29
  builtIns: Readonly<Blocks>;
30
+ /** Who is visiting (copied and frozen); `null` for none. */
31
+ visitor?: Visitor | null;
32
+ /** The version it was created with: `undefined` for the current release. */
33
+ version?: string;
34
+ /** The date campaigns run at, in ms since the epoch. */
35
+ date: number;
36
+ /** The tests it was given, on or off by name (frozen); `undefined` for none. */
37
+ experiments?: Overrides;
38
+ /** The campaigns it was given, on or off by name (frozen); `undefined` for none. */
39
+ campaigns?: Overrides;
26
40
  onCollision?: (name: string) => void;
27
41
  telemetry?: ClientTelemetry;
28
42
  }
@@ -32,10 +46,36 @@ type Loaded = { resolver: Resolver; snapshot: Snapshot } | { error: CMSError };
32
46
  export class CMSClient implements Client {
33
47
  readonly #options: ClientOptions;
34
48
  readonly #reported = new WeakSet<CMSError>();
49
+ readonly #visitor: Visitor | null;
35
50
  #loaded: Promise<Loaded> | undefined;
51
+ /** The revision loaded, once it is. */
52
+ #revision: string | undefined;
36
53
 
37
54
  constructor(options: ClientOptions) {
38
55
  this.#options = options;
56
+ this.#visitor = copyVisitor(options.visitor);
57
+ }
58
+
59
+ get visitor(): Visitor | null {
60
+ return this.#visitor;
61
+ }
62
+
63
+ get version(): string | undefined {
64
+ return this.#options.version ?? this.#revision;
65
+ }
66
+
67
+ get date(): Date {
68
+ return new Date(this.#options.date);
69
+ }
70
+
71
+ /** Read by the built-in `split-traffic` (see ./current.ts). */
72
+ get [EXPERIMENT_OVERRIDES](): Overrides | undefined {
73
+ return this.#options.experiments;
74
+ }
75
+
76
+ /** Read by the built-in `calendar` (see ./current.ts). */
77
+ get [CAMPAIGN_OVERRIDES](): Overrides | undefined {
78
+ return this.#options.campaigns;
39
79
  }
40
80
 
41
81
  async resolve<T = unknown>(target: unknown, options: ResolveOptions = {}): Promise<Result<T>> {
@@ -102,16 +142,20 @@ export class CMSClient implements Client {
102
142
 
103
143
  #load(): Promise<Loaded> {
104
144
  this.#loaded ??= this.#options.load().then(
105
- (snapshot): Loaded => ({
106
- snapshot,
107
- resolver: new Resolver({
145
+ (snapshot): Loaded => {
146
+ this.#revision = snapshot.revision;
147
+ return {
108
148
  snapshot,
109
- blocks: this.#options.blocks,
110
- builtIns: this.#options.builtIns,
111
- onCollision: this.#options.onCollision,
112
- onBlock: this.#options.telemetry?.block,
113
- }),
114
- }),
149
+ resolver: new Resolver({
150
+ snapshot,
151
+ blocks: this.#options.blocks,
152
+ builtIns: this.#options.builtIns,
153
+ client: this,
154
+ onCollision: this.#options.onCollision,
155
+ onBlock: this.#options.telemetry?.block,
156
+ }),
157
+ };
158
+ },
115
159
  (error): Loaded => ({
116
160
  error: isResolutionError(error)
117
161
  ? error
@@ -131,6 +175,28 @@ export class CMSClient implements Client {
131
175
  }
132
176
  }
133
177
 
178
+ /**
179
+ * The client's own frozen copy of a visitor, so a caller changing its object
180
+ * later changes no client; `null` for anything that isn't one.
181
+ */
182
+ function copyVisitor(visitor: Visitor | null | undefined): Visitor | null {
183
+ if (typeof visitor !== "object" || visitor === null || typeof visitor.id !== "string") {
184
+ return null;
185
+ }
186
+ const strings = (value: unknown): string[] =>
187
+ Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
188
+ const copy: Visitor = {
189
+ id: visitor.id,
190
+ active: Object.freeze(strings(visitor.active)) as string[],
191
+ inactiveDrawn: Object.freeze(strings(visitor.inactiveDrawn)) as string[],
192
+ pct: Object.freeze(Object.assign(Object.create(null), visitor.pct)),
193
+ };
194
+ if (typeof visitor.exp === "object" && visitor.exp !== null) {
195
+ copy.exp = Object.freeze(Object.assign(Object.create(null), visitor.exp));
196
+ }
197
+ return Object.freeze(copy);
198
+ }
199
+
134
200
  /** Plain code-unit order, the same on every server and locale. */
135
201
  function byCodeUnit(a: string, b: string): number {
136
202
  return a < b ? -1 : a > b ? 1 : 0;