@decocms/blocks 7.82.0 → 7.83.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@decocms/blocks",
3
- "version": "7.82.0",
3
+ "version": "7.83.0",
4
4
  "type": "module",
5
5
  "engines": {
6
6
  "node": ">=24"
@@ -25,36 +25,42 @@ async function render(props: Record<string, unknown> = {}) {
25
25
  }
26
26
 
27
27
  describe("Stats", () => {
28
- it("is mounted by the framework, so rendering it unconditionally must be inert", async () => {
29
- // DecoRootLayout renders <Stats /> for every site, enabled or not. That is only safe
30
- // because the gate returns null rather than, say, rendering a script pointing at nothing
31
- // -- a site that never opted in must emit no tag, no preconnect and no request.
32
- delete process.env.DECO_ANALYTICS_ENABLED;
28
+ it("is mounted by the framework, so rendering it with no key must be inert", async () => {
29
+ // DecoRootLayout renders <Stats /> for every site. On the collector's origin only a key
30
+ // identifies the site, so without one there is no tag, no preconnect and no request.
31
+ delete process.env.DECO_ANALYTICS_SITE_KEY;
33
32
  expect(await render()).toBe("");
34
33
  });
35
34
 
36
- it("renders nothing unless explicitly enabled", async () => {
37
- delete process.env.DECO_ANALYTICS_ENABLED;
38
- expect(await render()).toBe("");
35
+ it("loads from the collector's origin with a key, and preconnects to it", async () => {
36
+ process.env.DECO_ANALYTICS_SITE_KEY = "dq_abc123";
37
+ const html = await render();
38
+ expect(html).toContain('src="https://analytics.decocdn.com/_dq/a.js?k=dq_abc123"');
39
+ expect(html).toContain("preconnect");
40
+ });
39
41
 
40
- // Not "any truthy value". `ONEDOLLAR_ENABLED` defaults to ON and is disabled with
41
- // "false"; this one defaults to OFF and needs "true". A loose check here would make
42
- // `DECO_ANALYTICS_ENABLED=0` turn analytics on, which is the opposite of what anyone
43
- // setting it to 0 intends.
44
- process.env.DECO_ANALYTICS_ENABLED = "1";
45
- vi.resetModules();
42
+ it("renders nothing when explicitly disabled, even with a key or first-party", async () => {
43
+ process.env.DECO_ANALYTICS_ENABLED = "false";
44
+ process.env.DECO_ANALYTICS_SITE_KEY = "dq_abc123";
45
+ process.env.DECO_ANALYTICS_FIRST_PARTY = "true";
46
46
  expect(await render()).toBe("");
47
47
  });
48
48
 
49
- it("points at the same origin by default, and preconnects only when it does not", async () => {
50
- process.env.DECO_ANALYTICS_ENABLED = "true";
51
- const same = await render();
52
- expect(same).toContain('src="/_dq/a.js"');
49
+ it("is first-party only when opted in: same origin, no key needed, no preconnect", async () => {
50
+ process.env.DECO_ANALYTICS_FIRST_PARTY = "true";
51
+ const html = await render();
52
+ expect(html).toContain('src="/_dq/a.js"');
53
53
  // A preconnect to the page's own origin is a wasted hint, and on some browsers a
54
54
  // second connection opened for nothing.
55
- expect(same).not.toContain("preconnect");
55
+ expect(html).not.toContain("preconnect");
56
56
 
57
+ // Only the exact string opts in.
57
58
  vi.resetModules();
59
+ process.env.DECO_ANALYTICS_FIRST_PARTY = "1";
60
+ expect(await render()).toBe("");
61
+ });
62
+
63
+ it("uses a custom origin as given, with or without a key", async () => {
58
64
  process.env.DECO_ANALYTICS_ORIGIN = "https://analytics.example.com";
59
65
  const cross = await render();
60
66
  expect(cross).toContain('src="https://analytics.example.com/_dq/a.js"');
@@ -62,7 +68,7 @@ describe("Stats", () => {
62
68
  });
63
69
 
64
70
  it("carries dev and debug as attributes, and omits them when off", async () => {
65
- process.env.DECO_ANALYTICS_ENABLED = "true";
71
+ process.env.DECO_ANALYTICS_FIRST_PARTY = "true";
66
72
  // The whole reason these are attributes: TanStack hoists `<script async>` into `<head>`
67
73
  // above any inline config block, so a global set alongside the tag loses the race and the
68
74
  // collector boots into silence with no error.
@@ -79,8 +85,8 @@ describe("Stats", () => {
79
85
  });
80
86
 
81
87
  it("puts the site key in the URL, because that is where the collector reads it", async () => {
82
- process.env.DECO_ANALYTICS_ENABLED = "true";
83
- // Sites behind our edge are identified by the Host header, which a visitor cannot forge.
88
+ process.env.DECO_ANALYTICS_FIRST_PARTY = "true";
89
+ // First-party sites are identified by the Host header, which a visitor cannot forge.
84
90
  // Emitting an empty key would put a `tag`-sourced identity on a site that has a
85
91
  // trustworthy one, and `tag` is the source that must never reach an invoice.
86
92
  const none = await render();
@@ -99,7 +105,7 @@ describe("Stats", () => {
99
105
  });
100
106
 
101
107
  it("uses defer only when asked, async otherwise", async () => {
102
- process.env.DECO_ANALYTICS_ENABLED = "true";
108
+ process.env.DECO_ANALYTICS_FIRST_PARTY = "true";
103
109
  // Nothing visual may depend on this script. `async` is what keeps a slow or failed
104
110
  // collector from becoming a slow or broken page.
105
111
  expect(await render()).toContain("async");
@@ -46,28 +46,31 @@
46
46
  * development host, skip, and say nothing. Attributes cannot lose that race because
47
47
  * they are on the element that is executing.
48
48
  *
49
- * ## Off by default
49
+ * ## Third-party by default
50
50
  *
51
- * `DECO_ANALYTICS_ENABLED` must be set to `true`. This is the inverse of
52
- * `ONEDOLLAR_ENABLED`, which defaults to on, and the asymmetry is deliberate: one is
53
- * the incumbent and the other is being introduced. The two gates are also
54
- * independent, so a site can run both during a shadow comparison and neither gate
55
- * can turn the other off.
51
+ * The tag loads from the collector's origin and `DECO_ANALYTICS_SITE_KEY` identifies
52
+ * the site. Without a key it renders nothing: on that origin nothing else identifies
53
+ * the site, so its events would be dropped. `DECO_ANALYTICS_FIRST_PARTY=true` opts
54
+ * into the site's own host, which must route `/_dq/*` to the collector.
55
+ *
56
+ * `DECO_ANALYTICS_ENABLED=false` turns it off. That gate and `ONEDOLLAR_ENABLED` are
57
+ * independent, so a site can run both during a shadow comparison and neither can turn
58
+ * the other off.
56
59
  */
57
60
 
58
61
  export interface Props {
59
62
  /**
60
- * Where the collector is published. Empty means same-origin, which is the
61
- * intended deployment: the script and the beacon are served from the site's own
62
- * hostname so no third-party request is involved and nothing is blocked.
63
+ * Where the collector is published. Empty means same-origin: the script and the
64
+ * beacon are served from the site's own hostname, which must route `/_dq/*` to the
65
+ * collector.
63
66
  */
64
67
  origin?: string;
65
68
  /**
66
- * The site's public key, for sites NOT served through our CDN.
69
+ * The site's public key, which identifies it on the collector's origin.
67
70
  *
68
- * Sites behind our edge are identified by the `Host` header, which a visitor
69
- * cannot forge; those must leave this unset. A key travels in the page source
70
- * where anyone can read and reuse it, so a key-identified site is recorded with
71
+ * First-party sites are identified by the `Host` header, which a visitor cannot
72
+ * forge; those must leave this unset. A key travels in the page source where anyone
73
+ * can read and reuse it, so a key-identified site is recorded with
71
74
  * `site_id_source = tag` and is never billed from.
72
75
  */
73
76
  siteKey?: string;
@@ -82,21 +85,23 @@ export interface Props {
82
85
  debug?: boolean;
83
86
  }
84
87
 
85
- /** Same-origin. See {@link Props.origin}. */
86
- export const DEFAULT_ORIGIN = "";
88
+ /** The collector's own origin. See {@link Props.origin}. */
89
+ export const DEFAULT_ORIGIN = "https://analytics.decocdn.com";
87
90
 
88
91
  /**
89
- * Opt-in, and independent of `ONEDOLLAR_ENABLED` so both can run at once.
92
+ * On unless "false", and independent of `ONEDOLLAR_ENABLED` so both can run at once.
90
93
  */
91
- const DECO_ANALYTICS_ENABLED = process.env.DECO_ANALYTICS_ENABLED === "true";
94
+ const DECO_ANALYTICS_ENABLED = process.env.DECO_ANALYTICS_ENABLED !== "false";
95
+ const DECO_ANALYTICS_FIRST_PARTY = process.env.DECO_ANALYTICS_FIRST_PARTY === "true";
92
96
  const DECO_ANALYTICS_ORIGIN = process.env.DECO_ANALYTICS_ORIGIN;
93
97
  const DECO_ANALYTICS_SITE_KEY = process.env.DECO_ANALYTICS_SITE_KEY;
94
98
 
95
99
  function Stats({ origin, siteKey, defer, dev, debug }: Props) {
96
100
  if (!DECO_ANALYTICS_ENABLED) return null;
97
101
 
98
- const base = origin ?? DECO_ANALYTICS_ORIGIN ?? DEFAULT_ORIGIN;
102
+ const base = origin ?? DECO_ANALYTICS_ORIGIN ?? (DECO_ANALYTICS_FIRST_PARTY ? "" : DEFAULT_ORIGIN);
99
103
  const key = siteKey ?? DECO_ANALYTICS_SITE_KEY;
104
+ if (base === DEFAULT_ORIGIN && !key) return null;
100
105
 
101
106
  return (
102
107
  <>