@decocms/blocks 8.16.1 → 8.18.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/dist/v8/analytics/client.d.ts +48 -0
- package/dist/v8/analytics/client.d.ts.map +1 -0
- package/dist/v8/analytics/client.js +71 -0
- package/dist/v8/analytics/client.js.map +1 -0
- package/dist/v8/analytics/runtime/modules/click.d.ts +2 -0
- package/dist/v8/analytics/runtime/modules/click.d.ts.map +1 -0
- package/dist/v8/analytics/runtime/modules/click.js +48 -0
- package/dist/v8/analytics/runtime/modules/click.js.map +1 -0
- package/dist/v8/analytics/runtime/modules/commerce.d.ts +2 -0
- package/dist/v8/analytics/runtime/modules/commerce.d.ts.map +1 -0
- package/dist/v8/analytics/runtime/modules/commerce.js +41 -0
- package/dist/v8/analytics/runtime/modules/commerce.js.map +1 -0
- package/dist/v8/analytics/runtime/modules/consent.d.ts +33 -0
- package/dist/v8/analytics/runtime/modules/consent.d.ts.map +1 -0
- package/dist/v8/analytics/runtime/modules/consent.js +154 -0
- package/dist/v8/analytics/runtime/modules/consent.js.map +1 -0
- package/dist/v8/analytics/runtime/modules/deco.d.ts +2 -0
- package/dist/v8/analytics/runtime/modules/deco.d.ts.map +1 -0
- package/dist/v8/analytics/runtime/modules/deco.js +209 -0
- package/dist/v8/analytics/runtime/modules/deco.js.map +1 -0
- package/dist/v8/analytics/runtime/modules/engagement.d.ts +2 -0
- package/dist/v8/analytics/runtime/modules/engagement.d.ts.map +1 -0
- package/dist/v8/analytics/runtime/modules/engagement.js +128 -0
- package/dist/v8/analytics/runtime/modules/engagement.js.map +1 -0
- package/dist/v8/analytics/runtime/modules/errors.d.ts +2 -0
- package/dist/v8/analytics/runtime/modules/errors.d.ts.map +1 -0
- package/dist/v8/analytics/runtime/modules/errors.js +167 -0
- package/dist/v8/analytics/runtime/modules/errors.js.map +1 -0
- package/dist/v8/analytics/runtime/modules/heatmap.d.ts +2 -0
- package/dist/v8/analytics/runtime/modules/heatmap.d.ts.map +1 -0
- package/dist/v8/analytics/runtime/modules/heatmap.js +316 -0
- package/dist/v8/analytics/runtime/modules/heatmap.js.map +1 -0
- package/dist/v8/analytics/runtime/modules/vitals.d.ts +2 -0
- package/dist/v8/analytics/runtime/modules/vitals.d.ts.map +1 -0
- package/dist/v8/analytics/runtime/modules/vitals.js +119 -0
- package/dist/v8/analytics/runtime/modules/vitals.js.map +1 -0
- package/dist/v8/analytics/runtime/src/guards.d.ts +10 -0
- package/dist/v8/analytics/runtime/src/guards.d.ts.map +1 -0
- package/dist/v8/analytics/runtime/src/guards.js +70 -0
- package/dist/v8/analytics/runtime/src/guards.js.map +1 -0
- package/dist/v8/analytics/runtime/src/index.d.ts +2 -0
- package/dist/v8/analytics/runtime/src/index.d.ts.map +1 -0
- package/dist/v8/analytics/runtime/src/index.js +562 -0
- package/dist/v8/analytics/runtime/src/index.js.map +1 -0
- package/dist/v8/analytics/runtime/src/queue.d.ts +15 -0
- package/dist/v8/analytics/runtime/src/queue.d.ts.map +1 -0
- package/dist/v8/analytics/runtime/src/queue.js +36 -0
- package/dist/v8/analytics/runtime/src/queue.js.map +1 -0
- package/dist/v8/analytics/runtime/src/trim.d.ts +13 -0
- package/dist/v8/analytics/runtime/src/trim.d.ts.map +1 -0
- package/dist/v8/analytics/runtime/src/trim.js +38 -0
- package/dist/v8/analytics/runtime/src/trim.js.map +1 -0
- package/dist/v8/analytics/runtime/view/heat-core.d.ts +69 -0
- package/dist/v8/analytics/runtime/view/heat-core.d.ts.map +1 -0
- package/dist/v8/analytics/runtime/view/heat-core.js +314 -0
- package/dist/v8/analytics/runtime/view/heat-core.js.map +1 -0
- package/dist/v8/analytics/runtime/view/view.d.ts +51 -0
- package/dist/v8/analytics/runtime/view/view.d.ts.map +1 -0
- package/dist/v8/analytics/runtime/view/view.js +525 -0
- package/dist/v8/analytics/runtime/view/view.js.map +1 -0
- package/dist/v8/analytics/shared/anchor.d.ts +71 -0
- package/dist/v8/analytics/shared/anchor.d.ts.map +1 -0
- package/dist/v8/analytics/shared/anchor.js +155 -0
- package/dist/v8/analytics/shared/anchor.js.map +1 -0
- package/dist/v8/analytics/shared/contract.d.ts +294 -0
- package/dist/v8/analytics/shared/contract.d.ts.map +1 -0
- package/dist/v8/analytics/shared/contract.js +652 -0
- package/dist/v8/analytics/shared/contract.js.map +1 -0
- package/dist/v8/builtins/data.d.ts +20 -6
- package/dist/v8/builtins/data.d.ts.map +1 -1
- package/dist/v8/builtins/data.js +33 -8
- package/dist/v8/builtins/data.js.map +1 -1
- package/dist/v8/cms.js +2 -2
- package/dist/v8/cms.js.map +1 -1
- package/dist/v8/settings.d.ts +28 -9
- package/dist/v8/settings.d.ts.map +1 -1
- package/dist/v8/settings.js +6 -10
- package/dist/v8/settings.js.map +1 -1
- package/dist/v8/telemetry.d.ts +13 -11
- package/dist/v8/telemetry.d.ts.map +1 -1
- package/dist/v8/telemetry.js +27 -17
- package/dist/v8/telemetry.js.map +1 -1
- package/dist/v8/types.d.ts +7 -3
- package/dist/v8/types.d.ts.map +1 -1
- package/package.json +6 -1
- package/skills/deco-storefront-performance/references/render-location.md +3 -2
- package/skills/deco-v7-to-v8-migration/references/telemetry.md +1 -1
- package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +1 -1
- package/src/v8/analytics/client.ts +110 -0
- package/src/v8/analytics/runtime/globals.d.ts +36 -0
- package/src/v8/analytics/runtime/modules/click.ts +54 -0
- package/src/v8/analytics/runtime/modules/commerce.ts +73 -0
- package/src/v8/analytics/runtime/modules/consent.ts +150 -0
- package/src/v8/analytics/runtime/modules/deco.ts +207 -0
- package/src/v8/analytics/runtime/modules/engagement.ts +140 -0
- package/src/v8/analytics/runtime/modules/errors.ts +217 -0
- package/src/v8/analytics/runtime/modules/heatmap.ts +360 -0
- package/src/v8/analytics/runtime/modules/vitals.ts +128 -0
- package/src/v8/analytics/runtime/src/guards.ts +70 -0
- package/src/v8/analytics/runtime/src/index.ts +606 -0
- package/src/v8/analytics/runtime/src/queue.ts +40 -0
- package/src/v8/analytics/runtime/src/trim.ts +39 -0
- package/src/v8/analytics/runtime/view/heat-core.ts +335 -0
- package/src/v8/analytics/runtime/view/view.ts +596 -0
- package/src/v8/analytics/shared/anchor.ts +171 -0
- package/src/v8/analytics/shared/contract.ts +691 -0
- package/src/v8/analytics/tsconfig.json +14 -0
- package/src/v8/builtins/data.ts +44 -9
- package/src/v8/cms.ts +4 -4
- package/src/v8/settings.ts +13 -16
- package/src/v8/telemetry.ts +33 -29
- package/src/v8/types.ts +7 -3
|
@@ -0,0 +1,691 @@
|
|
|
1
|
+
/** The payload contract — one definition, imported by the runtime and by the Worker.
|
|
2
|
+
*
|
|
3
|
+
* It lived in two files with duplicated constants, which is the reliable way to end up
|
|
4
|
+
* with a client truncating at 200 and a server truncating at 250. The runtime applies
|
|
5
|
+
* these rules to save bandwidth; the Worker applies them because the endpoint is public
|
|
6
|
+
* and the client is by definition untrusted. Same rules, different reasons.
|
|
7
|
+
*
|
|
8
|
+
* Fields deliberately do NOT share one charset. Applying a single rule everywhere is the
|
|
9
|
+
* mistake: `plp-ranking` is a frozen experiment key owned by another team and contains a
|
|
10
|
+
* hyphen, and an order id from a customer's OMS is opaque and case-sensitive. Normalising
|
|
11
|
+
* those would break a join and an invoice respectively.
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
export const LIMITS = {
|
|
15
|
+
requestBytes: 64 * 1024,
|
|
16
|
+
// What the runtime puts in ONE request, under `requestBytes` with room for the envelope. Also
|
|
17
|
+
// under the browser's 64 KB keepalive/beacon quota, so a final flush is never refused whole.
|
|
18
|
+
batchBytes: 56 * 1024,
|
|
19
|
+
eventsPerBatch: 50,
|
|
20
|
+
eventBytes: 1024,
|
|
21
|
+
errorEventBytes: 8 * 1024,
|
|
22
|
+
// `$heatmap`: one event per page view carrying its clicks, scroll and attention. Measured
|
|
23
|
+
// ~450-500 B for a typical storefront view; the client sheds its newest clicks to stay
|
|
24
|
+
// under 3,800 B, so this is a ceiling the runtime never reaches on its own.
|
|
25
|
+
heatmapEventBytes: 4 * 1024,
|
|
26
|
+
hmClicks: 40, // click records per view (a rage burst is ONE record with a count)
|
|
27
|
+
hmRoots: 32, // root dictionary entries per view
|
|
28
|
+
hmBands: 40, // attention bands, 2.5% of the document each
|
|
29
|
+
hmRootLen: 120, // a root identity: manifest key + ordinal, or fs:<component>#n
|
|
30
|
+
queueMax: 200,
|
|
31
|
+
|
|
32
|
+
// GA4's limit. Anything valid there is valid here, so a migration does not hit a new
|
|
33
|
+
// ceiling on arrival.
|
|
34
|
+
nameLen: 40,
|
|
35
|
+
propKeys: 24, // GA4 allows 25
|
|
36
|
+
keyLen: 40,
|
|
37
|
+
valueLen: 200,
|
|
38
|
+
|
|
39
|
+
expEntries: 8,
|
|
40
|
+
expKeyLen: 60,
|
|
41
|
+
pathLen: 512,
|
|
42
|
+
refLen: 256,
|
|
43
|
+
itemIds: 20,
|
|
44
|
+
itemIdLen: 64,
|
|
45
|
+
transactionIdLen: 64, // order ids run longer than a prop key
|
|
46
|
+
flushMs: 10_000,
|
|
47
|
+
} as const;
|
|
48
|
+
|
|
49
|
+
/** `_trunc` is `LowCardinality(String)`. A free-text flag would rebuild the cardinality
|
|
50
|
+
* problem inside the column that exists to detect it, so the vocabulary is closed —
|
|
51
|
+
* and small, which keeps its dictionary at a handful of entries for the whole fleet. */
|
|
52
|
+
/** Flags are namespaced by the field they concern. `value.type` was ambiguous: there is
|
|
53
|
+
* also a column called `value` holding money, so a reader could not tell whether the flag
|
|
54
|
+
* meant "a prop was the wrong type" or "the amount would not parse". Now `props.*` is
|
|
55
|
+
* about the props map and `amount.*` is about money.
|
|
56
|
+
*
|
|
57
|
+
* The four the client needs are exported individually as well as in the map below.
|
|
58
|
+
* esbuild cannot tree-shake a single property off an object it sees referenced, so
|
|
59
|
+
* `FLAGS.propsCount` drags all twenty-one strings into the browser bundle. Naming them
|
|
60
|
+
* separately keeps the client at the four it uses. */
|
|
61
|
+
export const F_PROPS_COUNT = "props.count";
|
|
62
|
+
export const F_PROPS_TYPE = "props.type";
|
|
63
|
+
export const F_PROPS_LEN = "props.len";
|
|
64
|
+
export const F_QUEUE_OVERFLOW = "queue.overflow";
|
|
65
|
+
/** More events arrived in one request than `eventsPerBatch` allows. The surplus is discarded
|
|
66
|
+
* and the survivors carry this, so the loss is visible in the warehouse rather than inferred
|
|
67
|
+
* from a gap — the same contract `queue.overflow` makes on the client. */
|
|
68
|
+
export const F_BATCH_OVERFLOW = "batch.overflow";
|
|
69
|
+
|
|
70
|
+
export const FLAGS = {
|
|
71
|
+
nameEmpty: "name.empty",
|
|
72
|
+
nameCharset: "name.charset",
|
|
73
|
+
nameLen: "name.len",
|
|
74
|
+
nameReserved: "name.reserved",
|
|
75
|
+
keyCharset: "key.charset",
|
|
76
|
+
keyLen: "key.len",
|
|
77
|
+
propsCount: F_PROPS_COUNT,
|
|
78
|
+
propsType: F_PROPS_TYPE,
|
|
79
|
+
propsLen: F_PROPS_LEN,
|
|
80
|
+
propsControl: "props.control",
|
|
81
|
+
expCount: "exp.count",
|
|
82
|
+
expCharset: "exp.charset",
|
|
83
|
+
currencyInvalid: "currency.invalid",
|
|
84
|
+
amountType: "amount.type",
|
|
85
|
+
pathLen: "path.len",
|
|
86
|
+
refLen: "referrer.len",
|
|
87
|
+
itemIdsCount: "item_ids.count",
|
|
88
|
+
tsSkew: "ts.skew",
|
|
89
|
+
queueOverflow: F_QUEUE_OVERFLOW,
|
|
90
|
+
eventSize: "event.size",
|
|
91
|
+
// The sender's id was absent or not a UUID, so the Worker minted one. Recorded rather
|
|
92
|
+
// than silent because it costs the event its only dedup key: `uniqExact(event_id)` can
|
|
93
|
+
// no longer collapse a retry of the same event, and a number that quietly counts a
|
|
94
|
+
// retry twice is worse than one that says why.
|
|
95
|
+
eventIdMinted: "event_id.minted",
|
|
96
|
+
// Tier 0 identity for this row was built from a DERIVED salt because the day's stored one was
|
|
97
|
+
// missing — a cron that did not run. Derived from YESTERDAY's random salt, not from any
|
|
98
|
+
// secret, so the day is recomputable only until that salt expires from KV (around 03:10 UTC
|
|
99
|
+
// the following day), and then by nobody. Recorded rather than silent: "which days were recomputable,
|
|
100
|
+
// and for how long" has to be answerable from the warehouse. Rows written before 2026-10-27
|
|
101
|
+
// carry the same flag for a salt derived from `SALT_SECRET`/`VISITOR_SECRET`.
|
|
102
|
+
saltDerived: "salt.derived",
|
|
103
|
+
// Neither today's nor yesterday's salt was in KV, so this isolate minted a random salt for
|
|
104
|
+
// the day and holds it only in memory. Unrecomputable by anyone, and that costs counting:
|
|
105
|
+
// a visitor whose requests reach two isolates is two visitor_ids that day. Recorded so a
|
|
106
|
+
// fragmented day's unique counts are known to be inflated rather than trusted.
|
|
107
|
+
saltEphemeral: "salt.ephemeral",
|
|
108
|
+
// A tier 1 site sent a consented client id and there was no VISITOR_SECRET to hash it with,
|
|
109
|
+
// so this row fell back to tier 0 identity. Recorded because the failure is otherwise
|
|
110
|
+
// INVISIBLE AND EXPENSIVE: the site keeps collecting, every number looks right, and the one
|
|
111
|
+
// thing consent was collected to enable -- following the same person across days -- silently
|
|
112
|
+
// does not happen. The remedy is a deploy, so it has to be findable in the warehouse.
|
|
113
|
+
consentNoSecret: "consent.no_secret",
|
|
114
|
+
// DEPRECATED, never stamped any more. It meant "`SALT_SECRET` is unset, so tier 0's fallback
|
|
115
|
+
// would derive from `VISITOR_SECRET`". Tier 0 no longer has a secret at all (#13), so the
|
|
116
|
+
// state it described cannot exist. Declared still because rows written before 2026-10-27
|
|
117
|
+
// carry it, and this is where the `_trunc` vocabulary is closed.
|
|
118
|
+
saltSecretUnsplit: "salt.unsplit",
|
|
119
|
+
originMismatch: "origin.mismatch",
|
|
120
|
+
// An event or a prop key the site never declared. Recorded, never rejected: a taxonomy
|
|
121
|
+
// that drops data punishes the analyst for the developer's mistake, and the whole
|
|
122
|
+
// point of a registry is to make drift VISIBLE, not to lose the drifted data.
|
|
123
|
+
nameUnregistered: "name.unregistered",
|
|
124
|
+
propsUnregistered: "props.unregistered",
|
|
125
|
+
// The only two flags no collected event ever carries: they are written by `ops/backfill.mjs`
|
|
126
|
+
// on rows imported from the vendor we are replacing, and the Worker never sets them.
|
|
127
|
+
//
|
|
128
|
+
// They live here anyway, because this is where the `_trunc` vocabulary is CLOSED. A value in
|
|
129
|
+
// that column that is not declared here is off-contract, and the reason the vocabulary is
|
|
130
|
+
// closed at all -- keeping a LowCardinality dictionary at a handful of entries -- does not
|
|
131
|
+
// care which process wrote the row.
|
|
132
|
+
//
|
|
133
|
+
// `import.vendor` is provenance. `site_id_source = 'import'` already says a row was not
|
|
134
|
+
// collected; it does not say by whom, and the day a second vendor or a customer CSV arrives,
|
|
135
|
+
// "not host and not tag" identifies nothing.
|
|
136
|
+
//
|
|
137
|
+
// `import.day_grain` is a warning about the row's TIME. The vendor cannot report hours --
|
|
138
|
+
// `time:hour` collapses to a single bucket on their side -- so every imported event of a day
|
|
139
|
+
// sits at 00:00 of that day, and any hourly panel over an imported window is a midnight spike
|
|
140
|
+
// and nothing else. We do not synthesise a diurnal curve to make that chart look reasonable:
|
|
141
|
+
// an invented shape is worse than an absent one, because only the absent one is discoverable.
|
|
142
|
+
// This flag is how it is discovered.
|
|
143
|
+
//
|
|
144
|
+
// NEITHER IS A TRUST BOUNDARY. `flagSink` carries a payload's prior `_trunc` through without
|
|
145
|
+
// checking it against this list, so any browser can post either string -- as it already could
|
|
146
|
+
// before they were named here. The mark billing reads is `site_id_source`, which the Worker
|
|
147
|
+
// resolves and the payload cannot influence. These two are for a human reading a row.
|
|
148
|
+
// `$heatmap` only. `hm.len`: an array or a value was capped to its LIMITS bound. `hm.shape`:
|
|
149
|
+
// something was the wrong type or out of range and was DROPPED -- a click with no valid anchor
|
|
150
|
+
// hash, a section index pointing nowhere, a missing view id. Two flags rather than one per
|
|
151
|
+
// field, for the reason the vocabulary is closed at all.
|
|
152
|
+
hmLen: "hm.len",
|
|
153
|
+
hmShape: "hm.shape",
|
|
154
|
+
// `edge_events` only. The store's Worker called `EdgeIngest.write` without a bot score, so the
|
|
155
|
+
// row carries 99, the same "unknown, keep it" default a request without `cf.botManagement`
|
|
156
|
+
// gets on `workers.dev`. Marked because an RPC call carries no `request.cf` of its own: the
|
|
157
|
+
// score exists only if the caller forwarded it, and a funnel with bots quietly left in has to
|
|
158
|
+
// be findable.
|
|
159
|
+
edgeNoBotScore: "edge.no_bot_score",
|
|
160
|
+
importVendor: "import.vendor",
|
|
161
|
+
importDayGrain: "import.day_grain",
|
|
162
|
+
} as const;
|
|
163
|
+
|
|
164
|
+
export type Flag = (typeof FLAGS)[keyof typeof FLAGS];
|
|
165
|
+
export type Primitive = string | number | boolean;
|
|
166
|
+
export type Props = Record<string, Primitive>;
|
|
167
|
+
|
|
168
|
+
/** Platform events. Anything else arriving with a `$` is a site reaching into a namespace
|
|
169
|
+
* that is not its own: the prefix is stripped and the attempt recorded. */
|
|
170
|
+
/** Platform events. Anything else arriving with a `$` is a site reaching into a namespace
|
|
171
|
+
* that is not its own: the prefix is stripped and the attempt recorded.
|
|
172
|
+
*
|
|
173
|
+
* The engagement four are reserved for the same reason as the rest — they are generated
|
|
174
|
+
* by our module, not by the site, so a registry must not ask a site to declare them and
|
|
175
|
+
* a site must not be able to forge them. */
|
|
176
|
+
export const RESERVED_NAMES = [
|
|
177
|
+
"$pageview",
|
|
178
|
+
"$error",
|
|
179
|
+
"$vitals",
|
|
180
|
+
"$exposure",
|
|
181
|
+
"$scroll",
|
|
182
|
+
"$outbound",
|
|
183
|
+
"$download",
|
|
184
|
+
"$search",
|
|
185
|
+
// One per sampled page view, from the heatmap module. Reserved for the same two reasons as
|
|
186
|
+
// the engagement four, and the second matters more here: sampling is decided per VIEW by the
|
|
187
|
+
// module (`heatmapRate`), so the per-event valve must never touch it.
|
|
188
|
+
"$heatmap",
|
|
189
|
+
] as const;
|
|
190
|
+
|
|
191
|
+
/** Whether the sampling valve is allowed to drop this event.
|
|
192
|
+
*
|
|
193
|
+
* Sampling used to apply to EVERYTHING, `$pageview` included, and that is not what anyone
|
|
194
|
+
* else does: GA4 samples in the REPORT when a query exceeds its quota, never at
|
|
195
|
+
* collection, and Plausible does not sample at all. Dropping pageviews also produced the
|
|
196
|
+
* worst possible arithmetic — a visitor with k events survives a rate r with probability
|
|
197
|
+
* 1-(1-r)^k, so a nominal 10% sample kept ~50% of visitors while keeping exactly 10% of
|
|
198
|
+
* events, a five-fold overcount of uniques.
|
|
199
|
+
*
|
|
200
|
+
* The collector's own `$` events are exempt, and that dissolves the problem rather than
|
|
201
|
+
* mitigating it: every visit carries a `$pageview`, so if pageviews never drop then
|
|
202
|
+
* visitor counts are exact at any rate. They are also bounded per pageview by
|
|
203
|
+
* construction — one pageview, one vitals, one scroll, errors already collapsed into
|
|
204
|
+
* `error_count` — so exempting them sheds almost no volume.
|
|
205
|
+
*
|
|
206
|
+
* What floods a site is custom events: `track()` in a render loop is the emergency this
|
|
207
|
+
* valve exists for, and it is the only thing the valve now touches. */
|
|
208
|
+
export function isSampleable(name: string): boolean {
|
|
209
|
+
return !name.startsWith("$");
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/** What the store's own Worker may write through `EdgeIngest`, and the props each one carries.
|
|
213
|
+
*
|
|
214
|
+
* A CLOSED vocabulary, unlike the tag's. The edge is ours: these are the requests a store
|
|
215
|
+
* Worker sees on both sides of a Fresh x TanStack split, emitted by one wrapper rather than by
|
|
216
|
+
* each site's code, and that sameness is the whole reason they can be a ruler for an A/B test
|
|
217
|
+
* between two codebases. A name outside this list is refused and counted; a prop outside it is
|
|
218
|
+
* kept and flagged `props.unregistered`, like the site registry does.
|
|
219
|
+
*
|
|
220
|
+
* They land in `edge_events`, never in `raw_events` (D20), so no panel, rollup or session
|
|
221
|
+
* built on the tag ever counts a checkout API call as a page view. */
|
|
222
|
+
export const EDGE_EVENTS = {
|
|
223
|
+
/** One per HTML document, on both sides of the split. `og` is the orderGroup on the order
|
|
224
|
+
* confirmation (`/checkout/orderPlaced?og=`): it links a VTEX order to the visit that saw it.
|
|
225
|
+
* `sc` is the sales channel of the request; `cart` the hashed orderForm on checkout documents. */
|
|
226
|
+
$edge_page: ["page", "status", "prefetch", "cache", "ttfb_ms", "og", "sc", "cart", "fetch_site"],
|
|
227
|
+
/** One per call to the VTEX checkout API. `step` includes `gatewayCallback`. The cart shape
|
|
228
|
+
* (`qty` .. `items_value`, `payment`, `coupon`) is read from the orderForm that `shippingData`
|
|
229
|
+
* and `paymentData` return; `error` is the VTEX code and message on a status >= 400. */
|
|
230
|
+
checkout_step: [
|
|
231
|
+
"step",
|
|
232
|
+
"status",
|
|
233
|
+
"cart",
|
|
234
|
+
"payment",
|
|
235
|
+
"coupon",
|
|
236
|
+
"shipping_paid",
|
|
237
|
+
"items",
|
|
238
|
+
"referer",
|
|
239
|
+
"error",
|
|
240
|
+
"ms",
|
|
241
|
+
"from_checkout",
|
|
242
|
+
"qty",
|
|
243
|
+
"lines",
|
|
244
|
+
"sellers",
|
|
245
|
+
"packages",
|
|
246
|
+
"shipping",
|
|
247
|
+
"items_value",
|
|
248
|
+
],
|
|
249
|
+
/** One per call that changes the cart outside the checkout: `add`, `remove`, `update`,
|
|
250
|
+
* `coupon`, `simulate`. The route differs per side (v7's invoke route on Fresh, the TanStack
|
|
251
|
+
* invoke route), and the store Worker maps both to this. */
|
|
252
|
+
cart_action: ["action", "status", "cart", "items"],
|
|
253
|
+
/** What the shopper is paying and why, beside `checkout_step` on `shippingData` and
|
|
254
|
+
* `paymentData`: discounts, promotions, the orderForm's messages, unavailable items, gifts,
|
|
255
|
+
* who VTEX thinks the shopper is, and what the payment POST asked for. */
|
|
256
|
+
checkout_summary: [
|
|
257
|
+
"step",
|
|
258
|
+
"status",
|
|
259
|
+
"cart",
|
|
260
|
+
"value",
|
|
261
|
+
"items_value",
|
|
262
|
+
"discounts",
|
|
263
|
+
"shipping",
|
|
264
|
+
"qty",
|
|
265
|
+
"lines",
|
|
266
|
+
"promos",
|
|
267
|
+
"promo_hash",
|
|
268
|
+
"promo_names",
|
|
269
|
+
"messages",
|
|
270
|
+
"message_count",
|
|
271
|
+
"unavailable",
|
|
272
|
+
"selectable_gifts",
|
|
273
|
+
"gift_items",
|
|
274
|
+
"priced_items",
|
|
275
|
+
"utm_source",
|
|
276
|
+
"coupon",
|
|
277
|
+
"tags",
|
|
278
|
+
"channels",
|
|
279
|
+
"pay_systems",
|
|
280
|
+
"installments",
|
|
281
|
+
"pay_value",
|
|
282
|
+
"logged_in",
|
|
283
|
+
"can_edit",
|
|
284
|
+
"email",
|
|
285
|
+
"profile_id",
|
|
286
|
+
"saved_cards",
|
|
287
|
+
"saved_addresses",
|
|
288
|
+
"cookies",
|
|
289
|
+
],
|
|
290
|
+
/** The checkout page's own beacon, forwarded by the store Worker: JS errors, the step the
|
|
291
|
+
* shopper is on, the click on "place order" (`kind = buy`) and what followed it, the messages
|
|
292
|
+
* on screen, the exit. `kind` is the beacon's, `msg`/`aux`/`n` its three fields. */
|
|
293
|
+
checkout_js: ["kind", "msg", "aux", "n", "cart"],
|
|
294
|
+
} as const satisfies Record<string, readonly string[]>;
|
|
295
|
+
|
|
296
|
+
export type EdgeEventName = keyof typeof EDGE_EVENTS;
|
|
297
|
+
/** Props per edge event. Above the tag's `propKeys` because the vocabulary is closed and ours:
|
|
298
|
+
* `checkout_summary` carries 32 fields, and packing them into fewer keys would trade a query on
|
|
299
|
+
* a column for a parse of a string. */
|
|
300
|
+
export const EDGE_PROP_KEYS = 40;
|
|
301
|
+
/** Size budget per edge event, for the same reason: the tag's 1 KB is a budget for a visitor's
|
|
302
|
+
* upload on mobile data, and an edge event never travels over one. */
|
|
303
|
+
export const EDGE_EVENT_BYTES = 4096;
|
|
304
|
+
export const EDGE_EVENT_NAMES = Object.keys(EDGE_EVENTS) as EdgeEventName[];
|
|
305
|
+
|
|
306
|
+
/** The side of a Fresh x TanStack split, as an experiment.
|
|
307
|
+
*
|
|
308
|
+
* `withABTesting` (decocms/blocks, compat-v7) keeps the side in the `_deco_bucket` cookie as
|
|
309
|
+
* `<side>:<percent>`. The runtime's deco adapter reads it into `exp`, and the store Worker
|
|
310
|
+
* stamps the same pair on what it sends through `EdgeIngest`, so both halves of the funnel
|
|
311
|
+
* group by one experiment with one pair of variant names. Changing a value here without
|
|
312
|
+
* changing the store side splits the funnel in two. */
|
|
313
|
+
export const STOREFRONT_EXP = {
|
|
314
|
+
cookie: "_deco_bucket",
|
|
315
|
+
name: "storefront",
|
|
316
|
+
variants: { worker: "tanstack", fallback: "fresh" } as Record<string, string>,
|
|
317
|
+
} as const;
|
|
318
|
+
|
|
319
|
+
/** The campaign parameters worth a typed column, and nothing else. `utm` is a Map with
|
|
320
|
+
* LowCardinality keys: an open vocabulary is exactly how that becomes a cardinality
|
|
321
|
+
* problem, since anything appending `utm_<random>` to a URL would mint a key forever.
|
|
322
|
+
* The five UTM parameters are the standard set; `gclid` and `fbclid` are here because
|
|
323
|
+
* they are what actually arrives from paid traffic and are otherwise lost. */
|
|
324
|
+
export const CAMPAIGN_KEYS = [
|
|
325
|
+
"utm_source",
|
|
326
|
+
"utm_medium",
|
|
327
|
+
"utm_campaign",
|
|
328
|
+
"utm_term",
|
|
329
|
+
"utm_content",
|
|
330
|
+
"gclid",
|
|
331
|
+
"fbclid",
|
|
332
|
+
] as const;
|
|
333
|
+
|
|
334
|
+
/** Strip the `utm_` prefix on the way in: the column is already called `utm`, so storing
|
|
335
|
+
* `utm_source` spends five characters per row per key restating it. */
|
|
336
|
+
export const campaignKey = (raw: string): string | null => {
|
|
337
|
+
const k = raw.trim().toLowerCase();
|
|
338
|
+
// Accepts BOTH the raw form and the already-stripped one, because this runs twice:
|
|
339
|
+
// once in the browser reading the query string, and again in the Worker over whatever
|
|
340
|
+
// arrived. Accepting only `utm_source` meant the Worker dropped everything the runtime
|
|
341
|
+
// had correctly shortened to `source`, and only `gclid` survived — it has no prefix to
|
|
342
|
+
// strip. The endpoint is public anyway, so it has to handle either shape regardless of
|
|
343
|
+
// what our own runtime happens to send.
|
|
344
|
+
if ((CAMPAIGN_KEYS as readonly string[]).includes(k)) {
|
|
345
|
+
return k.startsWith("utm_") ? k.slice(4) : k;
|
|
346
|
+
}
|
|
347
|
+
return (CAMPAIGN_KEYS as readonly string[]).includes("utm_" + k) ? k : null;
|
|
348
|
+
};
|
|
349
|
+
|
|
350
|
+
/** Short keys on the wire, full names in the column. At 452M events a month, field names
|
|
351
|
+
* are a double-digit percentage of a 293-byte event — and the browser pays that upload on
|
|
352
|
+
* mobile data. Plausible does the same for the same reason. The Worker expands them, so
|
|
353
|
+
* nothing downstream ever sees the abbreviation. */
|
|
354
|
+
/** What a minted self-serve key looks like: a prefix and 22 URL-safe characters, the same
|
|
355
|
+
* shape the visitor hash uses.
|
|
356
|
+
*
|
|
357
|
+
* It lives in the CONTRACT rather than in the Worker's config module because it is one:
|
|
358
|
+
* whoever mints keys and whoever reads them have to agree, and those will not be the same
|
|
359
|
+
* codebase (D9). Deliberately NOT a secret — Plausible puts the equivalent in the script's
|
|
360
|
+
* filename, OneDollarStats uses the hostname itself, and a public identifier is the only
|
|
361
|
+
* thing a browser tag can carry. That is exactly why a key-sourced site is recorded as
|
|
362
|
+
* `tag` and never billed from. Checking the shape is a BOUND, not authentication: without
|
|
363
|
+
* it, any string of any length from any visitor becomes a KV read we pay for. */
|
|
364
|
+
export const KEY_SHAPE = /^dq_[A-Za-z0-9_-]{22}$/;
|
|
365
|
+
|
|
366
|
+
export const WIRE = {
|
|
367
|
+
event_id: "i",
|
|
368
|
+
/** A stable per-browser identifier, present ONLY on a tier-1 site whose visitor has
|
|
369
|
+
* granted consent. Absent otherwise, which is the whole point: at tier 0 there is
|
|
370
|
+
* nothing to send, and the Worker derives identity from a salt it rotates and forgets
|
|
371
|
+
* daily. Never stored as sent — the Worker hashes it with the site so the same browser
|
|
372
|
+
* is a different identifier on every customer's site. */
|
|
373
|
+
client_id: "ci",
|
|
374
|
+
ts: "t",
|
|
375
|
+
name: "n",
|
|
376
|
+
path: "p",
|
|
377
|
+
referrer: "r",
|
|
378
|
+
exp: "x",
|
|
379
|
+
props: "d",
|
|
380
|
+
value: "v",
|
|
381
|
+
currency: "c",
|
|
382
|
+
items_count: "q",
|
|
383
|
+
item_ids: "s",
|
|
384
|
+
transaction_id: "o",
|
|
385
|
+
error_type: "et",
|
|
386
|
+
error_message: "em",
|
|
387
|
+
error_file: "ef",
|
|
388
|
+
error_line: "el",
|
|
389
|
+
error_stack: "es",
|
|
390
|
+
error_fingerprint: "eg",
|
|
391
|
+
error_count: "ec",
|
|
392
|
+
utm: "u",
|
|
393
|
+
// Core Web Vitals go in typed columns rather than props: they are numbers that get
|
|
394
|
+
// averaged, bucketed and compared against thresholds, and a Map value would have to be
|
|
395
|
+
// parsed on every read. Nullable, because a metric that never fired must be absent
|
|
396
|
+
// rather than zero — a page nobody interacted with has no INP, and recording 0 would
|
|
397
|
+
// put it in the "good" bucket.
|
|
398
|
+
vital_lcp: "vl",
|
|
399
|
+
vital_inp: "vi",
|
|
400
|
+
vital_cls: "vc",
|
|
401
|
+
vital_ttfb: "vt",
|
|
402
|
+
vital_fcp: "vf",
|
|
403
|
+
// The heatmap module's per-view object. Expanded by the Worker into typed `hm_*` columns,
|
|
404
|
+
// never stored as sent. Shape in docs/PAYLOAD_CONTRACT.md.
|
|
405
|
+
heatmap: "hm",
|
|
406
|
+
_trunc: "_",
|
|
407
|
+
} as const;
|
|
408
|
+
|
|
409
|
+
const KEY_OK = /^[a-z][a-z0-9_]*$/;
|
|
410
|
+
const EXP_OK = /^[a-z0-9][a-z0-9_-]*$/; // hyphens: `plp-ranking`, `model-b`
|
|
411
|
+
const CONTROL = /[\x00-\x1F\x7F]/g;
|
|
412
|
+
const ISO4217 = /^[A-Z]{3}$/;
|
|
413
|
+
|
|
414
|
+
export type Sink = (f: Flag) => void;
|
|
415
|
+
|
|
416
|
+
/** snake_case, letter-initial, no spaces. The name becomes a panel label and a grouping
|
|
417
|
+
* key, so case and punctuation fragment one event across variants of itself — and a
|
|
418
|
+
* fragmented name also inflates the `LowCardinality` dictionary it lives in.
|
|
419
|
+
*
|
|
420
|
+
* Normalising is right. Doing it silently is not: two names collapsing into one is
|
|
421
|
+
* something the sender has to be able to see. */
|
|
422
|
+
export function normalizeName(
|
|
423
|
+
input: unknown,
|
|
424
|
+
flag: Sink,
|
|
425
|
+
reserved: readonly string[] = RESERVED_NAMES,
|
|
426
|
+
): string {
|
|
427
|
+
const raw = String(input ?? "").trim();
|
|
428
|
+
if (!raw) {
|
|
429
|
+
flag(FLAGS.nameEmpty);
|
|
430
|
+
return "unnamed";
|
|
431
|
+
}
|
|
432
|
+
|
|
433
|
+
if (raw.startsWith("$")) {
|
|
434
|
+
if (reserved.includes(raw)) return raw;
|
|
435
|
+
flag(FLAGS.nameReserved);
|
|
436
|
+
return normalizeName(raw.slice(1), flag, reserved);
|
|
437
|
+
}
|
|
438
|
+
|
|
439
|
+
let n = raw
|
|
440
|
+
.toLowerCase()
|
|
441
|
+
.replace(/[^a-z0-9_]/g, "_")
|
|
442
|
+
.replace(/_{2,}/g, "_")
|
|
443
|
+
.replace(/^_+|_+$/g, "");
|
|
444
|
+
if (!n) {
|
|
445
|
+
flag(FLAGS.nameEmpty);
|
|
446
|
+
return "unnamed";
|
|
447
|
+
}
|
|
448
|
+
if (!/^[a-z]/.test(n)) n = "e_" + n;
|
|
449
|
+
if (n !== raw) flag(FLAGS.nameCharset);
|
|
450
|
+
if (n.length > LIMITS.nameLen) {
|
|
451
|
+
n = n.slice(0, LIMITS.nameLen).replace(/_+$/, "");
|
|
452
|
+
flag(FLAGS.nameLen);
|
|
453
|
+
}
|
|
454
|
+
return n;
|
|
455
|
+
}
|
|
456
|
+
|
|
457
|
+
function normalizeKey(input: string, flag: Sink): string | null {
|
|
458
|
+
let k = input
|
|
459
|
+
.toLowerCase()
|
|
460
|
+
.replace(/[^a-z0-9_]/g, "_")
|
|
461
|
+
.replace(/_{2,}/g, "_")
|
|
462
|
+
.replace(/^_+|_+$/g, "");
|
|
463
|
+
if (!k) return null;
|
|
464
|
+
if (!/^[a-z]/.test(k)) k = "p_" + k;
|
|
465
|
+
if (k !== input) flag(FLAGS.keyCharset);
|
|
466
|
+
if (k.length > LIMITS.keyLen) {
|
|
467
|
+
k = k.slice(0, LIMITS.keyLen).replace(/_+$/, "");
|
|
468
|
+
flag(FLAGS.keyLen);
|
|
469
|
+
}
|
|
470
|
+
return KEY_OK.test(k) ? k : null;
|
|
471
|
+
}
|
|
472
|
+
|
|
473
|
+
/** Control characters are replaced rather than truncated around: a newline inside a value
|
|
474
|
+
* breaks line-oriented reads of the same data downstream, and a tab breaks TSV. */
|
|
475
|
+
export function normalizeProps(
|
|
476
|
+
input: unknown,
|
|
477
|
+
flag: Sink,
|
|
478
|
+
maxKeys: number = LIMITS.propKeys,
|
|
479
|
+
): Record<string, string> {
|
|
480
|
+
const out: Record<string, string> = {};
|
|
481
|
+
if (!input || typeof input !== "object" || Array.isArray(input)) return out;
|
|
482
|
+
|
|
483
|
+
let n = 0;
|
|
484
|
+
for (const [rawKey, rawValue] of Object.entries(input as Record<string, unknown>)) {
|
|
485
|
+
if (n >= maxKeys) {
|
|
486
|
+
flag(FLAGS.propsCount);
|
|
487
|
+
break;
|
|
488
|
+
}
|
|
489
|
+
if (rawValue === null || rawValue === undefined) continue;
|
|
490
|
+
|
|
491
|
+
const t = typeof rawValue;
|
|
492
|
+
if (t !== "string" && t !== "number" && t !== "boolean") {
|
|
493
|
+
flag(FLAGS.propsType);
|
|
494
|
+
continue;
|
|
495
|
+
}
|
|
496
|
+
|
|
497
|
+
const key = normalizeKey(rawKey, flag);
|
|
498
|
+
if (!key) {
|
|
499
|
+
flag(FLAGS.keyCharset);
|
|
500
|
+
continue;
|
|
501
|
+
}
|
|
502
|
+
|
|
503
|
+
let v = String(rawValue);
|
|
504
|
+
const stripped = v.replace(CONTROL, " ");
|
|
505
|
+
if (stripped !== v) {
|
|
506
|
+
v = stripped;
|
|
507
|
+
flag(FLAGS.propsControl);
|
|
508
|
+
}
|
|
509
|
+
if (v.length > LIMITS.valueLen) {
|
|
510
|
+
v = v.slice(0, LIMITS.valueLen);
|
|
511
|
+
flag(FLAGS.propsLen);
|
|
512
|
+
}
|
|
513
|
+
|
|
514
|
+
out[key] = v;
|
|
515
|
+
n++;
|
|
516
|
+
}
|
|
517
|
+
return out;
|
|
518
|
+
}
|
|
519
|
+
|
|
520
|
+
/** Case and hyphens preserved: these keys are a frozen contract owned elsewhere, and
|
|
521
|
+
* rewriting `plp-ranking` into `plp_ranking` would silently break the join they exist
|
|
522
|
+
* for. Invalid keys are dropped rather than coerced, for the same reason. */
|
|
523
|
+
export function normalizeExp(input: unknown, flag: Sink): Record<string, string> {
|
|
524
|
+
const out: Record<string, string> = {};
|
|
525
|
+
if (!input || typeof input !== "object" || Array.isArray(input)) return out;
|
|
526
|
+
|
|
527
|
+
let n = 0;
|
|
528
|
+
for (const [k, v] of Object.entries(input as Record<string, unknown>)) {
|
|
529
|
+
if (n >= LIMITS.expEntries) {
|
|
530
|
+
flag(FLAGS.expCount);
|
|
531
|
+
break;
|
|
532
|
+
}
|
|
533
|
+
const key = String(k).slice(0, LIMITS.expKeyLen);
|
|
534
|
+
const val = String(v ?? "").slice(0, LIMITS.expKeyLen);
|
|
535
|
+
if (!EXP_OK.test(key) || !EXP_OK.test(val)) {
|
|
536
|
+
flag(FLAGS.expCharset);
|
|
537
|
+
continue;
|
|
538
|
+
}
|
|
539
|
+
out[key] = val;
|
|
540
|
+
n++;
|
|
541
|
+
}
|
|
542
|
+
return out;
|
|
543
|
+
}
|
|
544
|
+
|
|
545
|
+
/** ISO 4217, three letters. Anything else is emptied and flagged: a half-valid currency on
|
|
546
|
+
* a revenue row is worse than a missing one. */
|
|
547
|
+
export function normalizeCurrency(input: unknown, flag: Sink): string {
|
|
548
|
+
const c = String(input ?? "")
|
|
549
|
+
.trim()
|
|
550
|
+
.toUpperCase();
|
|
551
|
+
if (!c) return "";
|
|
552
|
+
if (!ISO4217.test(c)) {
|
|
553
|
+
flag(FLAGS.currencyInvalid);
|
|
554
|
+
return "";
|
|
555
|
+
}
|
|
556
|
+
return c;
|
|
557
|
+
}
|
|
558
|
+
|
|
559
|
+
/** Unparseable becomes null and is flagged, never coerced to zero. A silent zero in a
|
|
560
|
+
* revenue report is a wrong number; a null is a missing one, and only one of those gets
|
|
561
|
+
* noticed. */
|
|
562
|
+
export function normalizeAmount(input: unknown, flag: Sink): number | null {
|
|
563
|
+
if (input === null || input === undefined || input === "") return null;
|
|
564
|
+
const n = Number(input);
|
|
565
|
+
if (!Number.isFinite(n)) {
|
|
566
|
+
flag(FLAGS.amountType);
|
|
567
|
+
return null;
|
|
568
|
+
}
|
|
569
|
+
return n;
|
|
570
|
+
}
|
|
571
|
+
|
|
572
|
+
/** Opaque and case-sensitive: it comes from the customer's order system, and it is what
|
|
573
|
+
* stops a reloaded confirmation page counting a sale twice. Only control bytes go. */
|
|
574
|
+
/** Canonical UUID form, which is what the `event_id` column accepts. Not a version check:
|
|
575
|
+
* a v4 from the runtime, a v7 from a server-side sender and a caller's own id are all
|
|
576
|
+
* fine, and refusing one of them would be inventing a contract nobody agreed to. */
|
|
577
|
+
const UUID_SHAPE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
|
|
578
|
+
|
|
579
|
+
/** An id that ClickHouse will accept, minted when the sender did not supply a usable one.
|
|
580
|
+
*
|
|
581
|
+
* This closes a hole that cost whole batches. `event_id` is a `UUID` column, and an absent
|
|
582
|
+
* id normalised to `""` -- which fails to parse, and a JSONEachRow INSERT fails as ONE
|
|
583
|
+
* statement. So a single event without an id destroyed every event in the same request,
|
|
584
|
+
* the sender got its 204, and the only trace was `events_lost`. Measured: one event with
|
|
585
|
+
* no `i` field, ClickHouse code 27, `inserted: 0`, `eventsLost: 1`.
|
|
586
|
+
*
|
|
587
|
+
* Our own runtime always sends one, which is exactly why this went unnoticed -- but the
|
|
588
|
+
* endpoint is public, and a server-side sender or a third-party SDK writing the lean
|
|
589
|
+
* version of our contract is not a hypothetical. `sanitize.ts` promises never to "reject a
|
|
590
|
+
* batch because one event is bad", and this is the one place it silently did. */
|
|
591
|
+
export function normalizeEventId(input: unknown, flag: Sink): string {
|
|
592
|
+
const v = normalizeOpaque(input, 36);
|
|
593
|
+
if (UUID_SHAPE.test(v)) return v;
|
|
594
|
+
flag(FLAGS.eventIdMinted);
|
|
595
|
+
return crypto.randomUUID();
|
|
596
|
+
}
|
|
597
|
+
|
|
598
|
+
export function normalizeOpaque(input: unknown, max: number): string {
|
|
599
|
+
return String(input ?? "")
|
|
600
|
+
.replace(CONTROL, "")
|
|
601
|
+
.slice(0, max);
|
|
602
|
+
}
|
|
603
|
+
|
|
604
|
+
export function normalizeItemIds(input: unknown, flag: Sink): string[] {
|
|
605
|
+
if (!Array.isArray(input)) return [];
|
|
606
|
+
if (input.length > LIMITS.itemIds) flag(FLAGS.itemIdsCount);
|
|
607
|
+
return input
|
|
608
|
+
.slice(0, LIMITS.itemIds)
|
|
609
|
+
.map((v) => normalizeOpaque(v, LIMITS.itemIdLen))
|
|
610
|
+
.filter(Boolean);
|
|
611
|
+
}
|
|
612
|
+
|
|
613
|
+
/** ClickHouse `DateTime64` in JSONEachRow wants `YYYY-MM-DD hh:mm:ss.mmm` — a `T` or a `Z`
|
|
614
|
+
* is a parse error, and a parse error rejects the whole batch rather than the row.
|
|
615
|
+
* Client clocks are wrong often enough that anything more than a day out is treated as
|
|
616
|
+
* skew and replaced, so one bad clock cannot poison a partition. */
|
|
617
|
+
/** The window is ASYMMETRIC, and that is the whole point.
|
|
618
|
+
*
|
|
619
|
+
* A timestamp in the past is ordinary: a beacon queued while the visitor was offline, a
|
|
620
|
+
* tab restored hours later, a phone that reconnects on the train. Up to a day of that is
|
|
621
|
+
* legitimate and gets kept.
|
|
622
|
+
*
|
|
623
|
+
* A timestamp in the FUTURE never is. An event cannot be received before it happened, so
|
|
624
|
+
* a future ts is always a wrong client clock — and browser clocks are wrong constantly.
|
|
625
|
+
* Accepting them symmetrically, as this did, means a visitor whose clock is twenty
|
|
626
|
+
* minutes fast pins their events to the top of the realtime feed and inflates "visitors
|
|
627
|
+
* now" until the world catches up. One skewed device could make the live view useless.
|
|
628
|
+
*
|
|
629
|
+
* Sixty seconds of forward tolerance covers ordinary jitter between the client's clock
|
|
630
|
+
* and ours; past that the event is stamped with receipt time and flagged, because the
|
|
631
|
+
* ORDER of a visitor's events is still worth preserving even when their clock is not.
|
|
632
|
+
*/
|
|
633
|
+
const PAST_TOLERANCE_MS = 86_400_000; // a day
|
|
634
|
+
const FUTURE_TOLERANCE_MS = 60_000; // clock jitter, nothing more
|
|
635
|
+
|
|
636
|
+
export function normalizeTs(input: unknown, flag: Sink): string {
|
|
637
|
+
const now = Date.now();
|
|
638
|
+
const t = Date.parse(String(input ?? ""));
|
|
639
|
+
if (!Number.isFinite(t) || now - t > PAST_TOLERANCE_MS || t - now > FUTURE_TOLERANCE_MS) {
|
|
640
|
+
flag(FLAGS.tsSkew);
|
|
641
|
+
return new Date(now).toISOString().replace("T", " ").replace("Z", "");
|
|
642
|
+
}
|
|
643
|
+
return new Date(t).toISOString().replace("T", " ").replace("Z", "");
|
|
644
|
+
}
|
|
645
|
+
|
|
646
|
+
/** Deduped and sorted, so two events that hit the same limits produce a byte-identical
|
|
647
|
+
* array — which is what lets the column compress instead of merely storing. */
|
|
648
|
+
export function flagSink(initial: readonly string[] = []) {
|
|
649
|
+
const set = new Set<string>(initial);
|
|
650
|
+
return {
|
|
651
|
+
flag: ((f: Flag) => {
|
|
652
|
+
set.add(f);
|
|
653
|
+
}) as Sink,
|
|
654
|
+
list: (): string[] => [...set].sort(),
|
|
655
|
+
};
|
|
656
|
+
}
|
|
657
|
+
|
|
658
|
+
/** The config fields the SERVED BUNDLE is built from — and nothing else.
|
|
659
|
+
*
|
|
660
|
+
* Purging on every config write would throw away the fleet's cache for changes that do not move
|
|
661
|
+
* a single byte of the script. `domains` is only ever read server-side, to cross-check an Origin
|
|
662
|
+
* against a declared key; `schema` drives validation in the Worker; `goals` belongs to the read
|
|
663
|
+
* side. None of them reach the browser.
|
|
664
|
+
*
|
|
665
|
+
* Kept here, next to the wire contract, because it is exactly that: a promise about what the
|
|
666
|
+
* bundle depends on. When `serveScript` starts reading another field, it goes in this list, and
|
|
667
|
+
* the test that compares the two catches it if it does not. */
|
|
668
|
+
export const BUNDLE_FIELDS = [
|
|
669
|
+
"id",
|
|
670
|
+
"sampling",
|
|
671
|
+
"tier",
|
|
672
|
+
"hash",
|
|
673
|
+
"modules",
|
|
674
|
+
"heatmapRate",
|
|
675
|
+
"errorHosts",
|
|
676
|
+
] as const;
|
|
677
|
+
|
|
678
|
+
/** A stable fingerprint of just those fields, for deciding whether a write needs a purge.
|
|
679
|
+
* Key order is fixed rather than whatever `JSON.stringify` produces from an object literal,
|
|
680
|
+
* since two configs equal in content must not differ here by the order someone typed them. */
|
|
681
|
+
export function bundleFingerprint(cfg: Record<string, unknown> | null | undefined): string {
|
|
682
|
+
if (!cfg) return "";
|
|
683
|
+
return JSON.stringify(
|
|
684
|
+
BUNDLE_FIELDS.map((f) => {
|
|
685
|
+
const v = cfg[f];
|
|
686
|
+
// Module ORDER does not change the bundle -- they are concatenated from a fixed map -- so
|
|
687
|
+
// a reorder must not look like a change.
|
|
688
|
+
return Array.isArray(v) ? [...v].map(String).sort() : (v ?? null);
|
|
689
|
+
}),
|
|
690
|
+
);
|
|
691
|
+
}
|