@splithub/node 0.1.9 → 0.2.1

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/index.js CHANGED
@@ -1,60 +1,194 @@
1
+ // src/handler.ts
2
+ import { isCrawler } from "@splithub/core";
3
+
1
4
  // src/results.ts
2
- import { getExperiment } from "@splithub/core";
3
- import { compareVariants, computeVerdict } from "@splithub/stats";
4
- function factorEffects(experiment, counts) {
5
+ import { getExperiment, HOLDOUT_KEY, holdoutExperiment } from "@splithub/core";
6
+ import { compareMeans, compareVariants, computeVerdict, estimateDaysToVerdict, holm, VERDICT_DEFAULTS } from "@splithub/stats";
7
+ var DAY_MS = 864e5;
8
+ function factorLevels(experiment, factor, counts2) {
9
+ return factor.levels.map((level) => {
10
+ const combos = experiment.variants.filter((v) => v.levels?.[factor.key] === level).map((v) => v.key);
11
+ const rows = counts2.filter((c) => combos.includes(c.variant));
12
+ return { variant: level, exposures: rows.reduce((s, r) => s + r.exposures, 0), conversions: rows.reduce((s, r) => s + r.conversions, 0) };
13
+ });
14
+ }
15
+ function factorPValues(experiment, counts2) {
16
+ const out = [];
17
+ for (const factor of experiment.factors ?? []) {
18
+ const perLevel = factorLevels(experiment, factor, counts2);
19
+ if (perLevel.every((l) => l.exposures > 0)) out.push(...compareVariants(perLevel).map((c) => c.sequential.pValue));
20
+ }
21
+ return out;
22
+ }
23
+ function factorEffects(experiment, counts2, options = {}) {
5
24
  if (!experiment.factors?.length) return [];
6
- return experiment.factors.map((factor) => {
7
- const perLevel = factor.levels.map((level) => {
8
- const combos = experiment.variants.filter((v) => v.levels?.[factor.key] === level).map((v) => v.key);
9
- const rows = counts.filter((c) => combos.includes(c.variant));
10
- return { variant: level, exposures: rows.reduce((s, r) => s + r.exposures, 0), conversions: rows.reduce((s, r) => s + r.conversions, 0) };
11
- });
12
- const comparisons = perLevel.every((l) => l.exposures > 0) ? compareVariants(perLevel) : [];
25
+ const perFactor = experiment.factors.map((factor) => {
26
+ const perLevel = factorLevels(experiment, factor, counts2);
27
+ return { factor, perLevel, comparisons: perLevel.every((l) => l.exposures > 0) ? compareVariants(perLevel) : [] };
28
+ });
29
+ const all = perFactor.flatMap((f) => f.comparisons);
30
+ const rejected = holm([...all.map((c) => c.sequential.pValue), ...options.familyPValues ?? []], 1 - VERDICT_DEFAULTS.confidence);
31
+ const significant = new Map(all.map((c, i) => [c, rejected[i]]));
32
+ return perFactor.map(({ factor, perLevel, comparisons }) => {
13
33
  const levels = perLevel.map((l, i) => {
14
- const cmp = comparisons.find((c) => c.variant === l.variant);
34
+ const cmp = i === 0 ? void 0 : comparisons.find((c) => c.variant === l.variant);
15
35
  return {
16
36
  level: l.variant,
17
37
  exposures: l.exposures,
18
38
  conversions: l.conversions,
19
39
  rate: l.exposures ? l.conversions / l.exposures : 0,
20
- relativeLift: i === 0 ? null : cmp?.relativeLift ?? null,
21
- pValue: i === 0 ? null : cmp?.pValue ?? null,
22
- significant: Boolean(cmp?.significant)
40
+ relativeLift: cmp?.relativeLift ?? null,
41
+ pValue: cmp?.pValue ?? null,
42
+ sequentialPValue: cmp?.sequential.pValue ?? null,
43
+ probabilityToBeat: cmp?.probabilityToBeat ?? null,
44
+ significant: cmp ? Boolean(significant.get(cmp)) : false
23
45
  };
24
46
  });
25
47
  const winners = levels.filter((l) => l.significant && (l.relativeLift ?? 0) > 0).sort((a, b) => (b.relativeLift ?? 0) - (a.relativeLift ?? 0));
26
48
  return { key: factor.key, levels, best: winners[0]?.level ?? null };
27
49
  });
28
50
  }
29
- async function experimentResults(config, store, key) {
30
- const experiment = getExperiment(config, key);
31
- if (!experiment) return null;
32
- const goal = experiment.goal;
33
- const observed = goal ? await store.variantCounts(key, goal) : [];
34
- const counts = experiment.variants.map((v) => {
51
+ var sum = (xs) => xs.reduce((s, x) => s + x, 0);
52
+ var sameShares = (a, b) => {
53
+ const sa = sum(a);
54
+ const sb = sum(b);
55
+ return a.every((x, i) => Math.abs(x / sa - b[i] / sb) < 1e-9);
56
+ };
57
+ function flowExpectedShares(experiment, flow) {
58
+ const keys = experiment.variants.map((v) => v.key);
59
+ const zero = () => new Array(keys.length).fill(0);
60
+ const memo = /* @__PURE__ */ new Map();
61
+ const walk = (id, depth) => {
62
+ if (!id) return { mass: zero(), known: true };
63
+ if (depth > 64) return "unknown";
64
+ const cached = memo.get(id);
65
+ if (cached) return cached;
66
+ const node = flow.nodes[id];
67
+ let out;
68
+ if (!node || node.type === "skip") out = { mass: zero(), known: true };
69
+ else if (node.type === "variant") {
70
+ const mass = zero();
71
+ const i = keys.indexOf(node.variant);
72
+ if (i >= 0) mass[i] = 1;
73
+ out = { mass, known: true };
74
+ } else {
75
+ const raw = node.type === "split" ? node.outputs.filter((o) => o.weight > 0).map((o) => ({ weight: o.weight, reach: walk(o.to, depth + 1) })) : [{ weight: 1, reach: walk(node.then, depth + 1) }, { weight: 1, reach: walk(node.else, depth + 1) }];
76
+ const branches = [];
77
+ for (const b of raw) if (b.reach !== "unknown") branches.push({ weight: b.weight, reach: b.reach });
78
+ const live = branches.filter((b) => sum(b.reach.mass) > 0);
79
+ if (branches.length < raw.length) out = "unknown";
80
+ else if (node.type === "split" && branches.every((b) => b.reach.known)) {
81
+ const total = sum(branches.map((b) => b.weight));
82
+ const mass = zero();
83
+ for (const b of branches) b.reach.mass.forEach((m, i) => mass[i] += b.weight / total * m);
84
+ out = { mass, known: true };
85
+ } else if (live.length === 0) out = { mass: zero(), known: true };
86
+ else if (live.every((b) => sameShares(b.reach.mass, live[0].reach.mass))) {
87
+ const ref = live[0].reach.mass;
88
+ out = { mass: ref.map((m) => m / sum(ref)), known: false };
89
+ } else out = "unknown";
90
+ }
91
+ memo.set(id, out);
92
+ return out;
93
+ };
94
+ const reach = walk(flow.start, 0);
95
+ if (reach === "unknown" || sum(reach.mass) <= 0) return null;
96
+ return reach.mass;
97
+ }
98
+ function resultsExperiment(config, key) {
99
+ return getExperiment(config, key) ?? (key === HOLDOUT_KEY ? holdoutExperiment(config) : null);
100
+ }
101
+ function alignCounts(experiment, observed) {
102
+ return experiment.variants.map((v) => {
35
103
  const row = observed.find((o) => o.variant === v.key);
36
- return { variant: v.key, exposures: row?.exposures ?? 0, conversions: row?.conversions ?? 0, revenue: row?.revenue ?? 0 };
104
+ return {
105
+ variant: v.key,
106
+ exposures: row?.exposures ?? 0,
107
+ conversions: row?.conversions ?? 0,
108
+ revenue: row?.revenue ?? row?.revenueSum ?? 0,
109
+ ...row?.revenueSum !== void 0 ? { revenueSum: row.revenueSum } : {},
110
+ ...row?.revenueSumSq !== void 0 ? { revenueSumSq: row.revenueSumSq } : {}
111
+ };
37
112
  });
38
- const verdict = goal ? computeVerdict(key, counts, { expectedWeights: experiment.variants.map((v) => v.weight) }) : { ...computeVerdict(key, [], {}), message: "No goal configured for this experiment; add `goal` in splithub.config.ts." };
39
- return { experiment: key, kind: experiment.kind, status: experiment.status, goal, description: experiment.description, verdict, ...experiment.kind === "mvt" && goal ? { factors: factorEffects(experiment, counts) } : {} };
113
+ }
114
+ async function metricInputs(experiment, store) {
115
+ const m = experiment.metrics;
116
+ if (!m) return [];
117
+ const list = [
118
+ ...m.secondary.map((metric) => ({ metric, role: "secondary" })),
119
+ ...m.guardrails.map((g) => ({ metric: g.goal, role: "guardrail", worse: g.worse }))
120
+ ];
121
+ return Promise.all(list.map(async (x) => ({ ...x, counts: alignCounts(experiment, await store.variantCounts(experiment.key, x.metric)) })));
122
+ }
123
+ async function experimentResults(config, store, key, options = {}) {
124
+ const experiment = resultsExperiment(config, key);
125
+ if (!experiment) return null;
126
+ const goal2 = experiment.goal;
127
+ const observed = goal2 ? await store.variantCounts(key, goal2) : [];
128
+ const counts2 = alignCounts(experiment, observed);
129
+ const metrics = goal2 ? await metricInputs(experiment, store) : [];
130
+ const now = options.now ?? /* @__PURE__ */ new Date();
131
+ const summary = options.summary !== void 0 ? options.summary : goal2 ? (await store.summaries()).find((s) => s.experiment === key) ?? null : null;
132
+ const span = summary?.firstExposureAt != null && summary.lastExposureAt != null ? (summary.lastExposureAt - summary.firstExposureAt) / DAY_MS : void 0;
133
+ const days = options.days ?? span;
134
+ const visitors = counts2.reduce((s, c) => s + c.exposures, 0);
135
+ const visitorsPerDay = options.visitorsPerDay ?? (days !== void 0 && days >= 1 / 24 && visitors > 0 ? visitors / days : null);
136
+ let expected = { expectedWeights: experiment.variants.map((v) => v.weight) };
137
+ if (experiment.flow) {
138
+ const shares = flowExpectedShares(experiment, experiment.flow);
139
+ expected = shares ? { expectedWeights: shares } : { skipSrm: "Split check skipped: targeting conditions decide which variant a visitor reaches, so the expected split depends on who visits." };
140
+ }
141
+ const isMvt = experiment.kind === "mvt" && Boolean(goal2);
142
+ const familyPValues = isMvt ? factorPValues(experiment, counts2) : void 0;
143
+ const limits = { ...experiment.minDays !== void 0 ? { minDays: experiment.minDays } : {}, ...experiment.goodSample !== void 0 ? { goodSample: experiment.goodSample } : {} };
144
+ const verdict = goal2 ? computeVerdict(key, counts2, { ...expected, days, familyPValues, now, ...limits, ...metrics.length ? { metrics } : {} }) : { ...computeVerdict(key, [], { now, ...limits }), message: "No goal configured for this experiment; add `goal` in splithub.config.ts." };
145
+ const factors = isMvt ? factorEffects(experiment, counts2, { familyPValues: verdict.comparisons.map((c) => c.sequential.pValue) }) : void 0;
146
+ const revenue = goal2 ? revenueResult(counts2, Boolean(config.goals.find((g) => g.key === goal2)?.revenue)) : void 0;
147
+ return {
148
+ experiment: key,
149
+ kind: experiment.kind,
150
+ status: experiment.status,
151
+ goal: goal2,
152
+ description: experiment.description,
153
+ verdict,
154
+ daysToVerdict: goal2 ? estimateDaysToVerdict(verdict, visitorsPerDay) : null,
155
+ visitorsPerDay: visitorsPerDay === null ? null : Math.round(visitorsPerDay * 10) / 10,
156
+ ...factors ? { factors } : {},
157
+ ...revenue ? { revenue } : {}
158
+ };
159
+ }
160
+ function revenueResult(counts2, goalHasRevenue) {
161
+ if (!counts2.every((c) => typeof c.revenueSumSq === "number")) return void 0;
162
+ const rows = counts2.map((c) => ({ variant: c.variant, n: c.exposures, sum: c.revenueSum ?? c.revenue ?? 0, sumSq: c.revenueSumSq ?? 0 }));
163
+ if (!goalHasRevenue && rows.every((r) => r.sum === 0)) return void 0;
164
+ return {
165
+ variants: rows.map((r) => ({ variant: r.variant, visitors: r.n, revenue: r.sum, perVisitor: r.n > 0 ? r.sum / r.n : 0 })),
166
+ comparisons: compareMeans(rows)
167
+ };
40
168
  }
41
169
  async function statusTable(config, store) {
42
170
  const summaries = await store.summaries();
43
171
  const byKey = new Map(summaries.map((s) => [s.experiment, s]));
44
172
  const rows = [];
45
- for (const exp of config.experiments) {
173
+ const holdout = holdoutExperiment(config);
174
+ const all = holdout && byKey.has(HOLDOUT_KEY) ? [...config.experiments, holdout] : config.experiments;
175
+ for (const exp of all) {
46
176
  const s = byKey.get(exp.key);
47
177
  const days = s?.firstExposureAt && s.lastExposureAt ? Math.max(1, Math.ceil((s.lastExposureAt - s.firstExposureAt) / 864e5)) : 0;
48
178
  let verdict = null;
49
179
  let headline = null;
50
180
  let best = null;
181
+ let sample = null;
182
+ let stars = null;
51
183
  if (exp.goal && s) {
52
- const r = await experimentResults(config, store, exp.key);
184
+ const r = await experimentResults(config, store, exp.key, { summary: s });
53
185
  verdict = r?.verdict.status ?? null;
54
186
  headline = r ? headlineFor(r.verdict) : null;
55
187
  best = r ? bestOf(r.verdict) : null;
188
+ sample = r?.verdict.sample.quality ?? null;
189
+ stars = r?.verdict.sample.stars ?? null;
56
190
  }
57
- rows.push({ experiment: exp.key, kind: exp.kind, status: exp.status, goal: exp.goal, description: exp.description ?? null, exposures: s?.exposures ?? 0, visitors: s?.visitors ?? 0, days, verdict, headline, best });
191
+ rows.push({ experiment: exp.key, kind: exp.kind, status: exp.status, goal: exp.goal, description: exp.description ?? null, exposures: s?.exposures ?? 0, visitors: s?.visitors ?? 0, days, verdict, headline, best, sample, stars });
58
192
  }
59
193
  return rows;
60
194
  }
@@ -75,6 +209,8 @@ function headlineFor(v) {
75
209
  return best ? `#${best.index} ${lift} (too early)` : "too early";
76
210
  case "srm_detected":
77
211
  return "SRM! check setup";
212
+ case "guardrail_breached":
213
+ return `guardrail hit: ${v.guardrailBreached?.[0]?.metric ?? "?"}`;
78
214
  case "no_significant_difference":
79
215
  return "no difference";
80
216
  default:
@@ -83,6 +219,7 @@ function headlineFor(v) {
83
219
  }
84
220
 
85
221
  // src/validate.ts
222
+ import { HOLDOUT_KEY as HOLDOUT_KEY2 } from "@splithub/core";
86
223
  var ID = /^[a-z0-9_-]{8,64}$/i;
87
224
  var KEY = /^[a-z0-9][a-z0-9_-]{0,63}$/;
88
225
  var MAX_EVENTS = 500;
@@ -113,7 +250,7 @@ function normalize(e, now) {
113
250
  const ts = Math.abs(e.ts - now) > MAX_SKEW_MS ? now : Math.round(e.ts);
114
251
  const url = typeof e.url === "string" ? e.url.slice(0, 512) : null;
115
252
  if (e.type === "exposure") {
116
- if (typeof e.exp !== "string" || !KEY.test(e.exp)) return "exposure.exp is invalid";
253
+ if (typeof e.exp !== "string" || !(KEY.test(e.exp) || e.exp === HOLDOUT_KEY2)) return "exposure.exp is invalid";
117
254
  if (typeof e.var !== "string" || !KEY.test(e.var)) return "exposure.var is invalid";
118
255
  return { id: e.id, type: "exposure", experiment: e.exp, variant: e.var, goal: null, visitorId: e.vid, sessionId: e.sid, ts, url, props: null, receivedAt: now };
119
256
  }
@@ -131,6 +268,8 @@ function normalize(e, now) {
131
268
  }
132
269
 
133
270
  // src/handler.ts
271
+ var isBotUserAgent = (ua) => isCrawler(ua);
272
+ var visitorUserAgent = (request) => request.headers.get("x-splithub-ua") ?? request.headers.get("user-agent");
134
273
  function createSplitHubHandler(options) {
135
274
  const { config, store } = options;
136
275
  const corsHeaders = (request) => {
@@ -165,6 +304,7 @@ function createSplitHubHandler(options) {
165
304
  }
166
305
  const result = validateBatch(body, config.project);
167
306
  if (!result.ok) return json(request, { error: result.error }, 400);
307
+ if (isBotUserAgent(visitorUserAgent(request))) return json(request, { ok: true, received: result.events.length, inserted: 0 }, 202);
168
308
  const inserted = await store.insertEvents(result.events);
169
309
  return json(request, { ok: true, received: result.events.length, inserted }, 202);
170
310
  }
@@ -215,11 +355,136 @@ async function toRequest(req) {
215
355
  if (method !== "GET" && method !== "HEAD") {
216
356
  const chunks = [];
217
357
  for await (const chunk of req) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
218
- body = Buffer.concat(chunks);
358
+ const all = Buffer.concat(chunks);
359
+ const copy = new Uint8Array(all.byteLength);
360
+ copy.set(all);
361
+ body = copy.buffer;
219
362
  }
220
363
  return new Request(url, { method, headers, body });
221
364
  }
222
365
 
366
+ // src/attribution.ts
367
+ var ATTRIBUTION_SKEW_MS = 6e4;
368
+ var GOAL_DAILY_CAP = 50;
369
+ var DAY_MS2 = 864e5;
370
+ function revenueOf(props) {
371
+ const v = props?.revenue;
372
+ return typeof v === "number" && Number.isFinite(v) ? v : 0;
373
+ }
374
+ function attributeVariants(events, experiment, goal2) {
375
+ const first = /* @__PURE__ */ new Map();
376
+ const goals = /* @__PURE__ */ new Map();
377
+ for (const e of events) {
378
+ if (e.type === "exposure") {
379
+ if (e.experiment !== experiment || !e.variant) continue;
380
+ const prev = first.get(e.visitorId);
381
+ if (prev === void 0 || e.ts < prev.ts || e.ts === prev.ts && e.variant < prev.variant) first.set(e.visitorId, { variant: e.variant, ts: e.ts });
382
+ } else if (e.goal === goal2) {
383
+ const key = `${e.visitorId}\0${e.ts - e.ts % DAY_MS2}`;
384
+ const list = goals.get(key) ?? [];
385
+ list.push(e);
386
+ goals.set(key, list);
387
+ }
388
+ }
389
+ const counted = /* @__PURE__ */ new Map();
390
+ const revenueByVisitor = /* @__PURE__ */ new Map();
391
+ for (const list of goals.values()) {
392
+ list.sort((a, b) => a.ts - b.ts || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
393
+ for (const g of list.slice(0, GOAL_DAILY_CAP)) {
394
+ (counted.get(g.visitorId) ?? counted.set(g.visitorId, []).get(g.visitorId)).push(g.ts);
395
+ (revenueByVisitor.get(g.visitorId) ?? revenueByVisitor.set(g.visitorId, []).get(g.visitorId)).push(revenueOf(g.props));
396
+ }
397
+ }
398
+ const out = /* @__PURE__ */ new Map();
399
+ for (const [visitor, { variant, ts }] of first) {
400
+ const row = out.get(variant) ?? { variant, exposures: 0, conversions: 0, revenue: 0, revenueSum: 0, revenueSumSq: 0 };
401
+ row.exposures++;
402
+ const times = counted.get(visitor) ?? [];
403
+ const revenues = revenueByVisitor.get(visitor) ?? [];
404
+ let converted = false;
405
+ let revenue = 0;
406
+ times.forEach((t, i) => {
407
+ if (t < ts - ATTRIBUTION_SKEW_MS) return;
408
+ converted = true;
409
+ revenue += revenues[i];
410
+ });
411
+ if (converted) {
412
+ row.conversions++;
413
+ row.revenueSum += revenue;
414
+ row.revenueSumSq += revenue * revenue;
415
+ row.revenue = row.revenueSum;
416
+ }
417
+ out.set(variant, row);
418
+ }
419
+ return [...out.values()];
420
+ }
421
+ var IDENT = /^[a-z_][a-z0-9_]*$/i;
422
+ function revenueExpr(dialect, alias) {
423
+ if (dialect === "postgres") return `CASE WHEN jsonb_typeof(${alias}.props::jsonb -> 'revenue') = 'number' THEN (${alias}.props::jsonb ->> 'revenue')::float8 ELSE 0 END`;
424
+ if (dialect === "mysql") return `CASE WHEN JSON_TYPE(JSON_EXTRACT(${alias}.props, '$.revenue')) IN ('INTEGER', 'UNSIGNED INTEGER', 'DOUBLE', 'DECIMAL') THEN JSON_EXTRACT(${alias}.props, '$.revenue') + 0 ELSE 0 END`;
425
+ return `CASE WHEN json_type(${alias}.props, '$.revenue') IN ('integer', 'real') THEN json_extract(${alias}.props, '$.revenue') ELSE 0 END`;
426
+ }
427
+ function variantCountsSql(options) {
428
+ const { dialect } = options;
429
+ const t = options.table ?? "splithub_events";
430
+ if (!IDENT.test(t)) throw new Error("[splithub] invalid table name");
431
+ if (options.projectColumn !== void 0 && !IDENT.test(options.projectColumn)) throw new Error("[splithub] invalid column name");
432
+ const params = [];
433
+ const p = (name) => {
434
+ if (dialect === "postgres") {
435
+ const i = params.indexOf(name);
436
+ if (i >= 0) return `$${i + 1}`;
437
+ params.push(name);
438
+ return `$${params.length}`;
439
+ }
440
+ params.push(name);
441
+ return "?";
442
+ };
443
+ const proj = (alias) => options.projectColumn ? `${alias}.${options.projectColumn} = ${p("project")} AND ` : "";
444
+ const fv = `SELECT x.visitor_id, MIN(x.ts) AS first_ts FROM ${t} x WHERE ${proj("x")}x.type = 'exposure' AND x.experiment = ${p("experiment")} GROUP BY x.visitor_id`;
445
+ const fe = `SELECT MIN(e.variant) AS variant, fv.visitor_id, fv.first_ts
446
+ FROM (${fv}) fv
447
+ JOIN ${t} e ON ${proj("e")}e.type = 'exposure' AND e.experiment = ${p("experiment")} AND e.visitor_id = fv.visitor_id AND e.ts = fv.first_ts
448
+ GROUP BY fv.visitor_id, fv.first_ts`;
449
+ const goalJoin = `${proj("g")}g.type = 'goal' AND g.goal = ${p("goal")} AND g.visitor_id = fe.visitor_id AND g.ts >= fe.first_ts - ${ATTRIBUTION_SKEW_MS}
450
+ AND (SELECT COUNT(*) FROM ${t} g2
451
+ WHERE ${proj("g2")}g2.type = 'goal' AND g2.goal = g.goal AND g2.visitor_id = g.visitor_id
452
+ AND g2.ts >= g.ts - (g.ts % ${DAY_MS2}) AND (g2.ts < g.ts OR (g2.ts = g.ts AND g2.id < g.id))) < ${GOAL_DAILY_CAP}`;
453
+ const sql = `SELECT v.variant AS variant, COUNT(*) AS exposures, SUM(v.converted) AS conversions,
454
+ COALESCE(SUM(v.revenue), 0) AS revenue_sum, COALESCE(SUM(v.revenue * v.revenue), 0) AS revenue_sum_sq
455
+ FROM (
456
+ SELECT fe.variant, fe.visitor_id,
457
+ CASE WHEN COUNT(g.id) > 0 THEN 1 ELSE 0 END AS converted,
458
+ COALESCE(SUM(${revenueExpr(dialect, "g")}), 0) AS revenue
459
+ FROM (${fe}) fe
460
+ LEFT JOIN ${t} g ON ${goalJoin}
461
+ GROUP BY fe.variant, fe.visitor_id
462
+ ) v
463
+ GROUP BY v.variant`;
464
+ return {
465
+ sql,
466
+ params,
467
+ bind(values) {
468
+ return params.map((name) => {
469
+ const v = values[name];
470
+ if (v === void 0) throw new Error(`[splithub] missing "${name}" for the attribution query`);
471
+ return v;
472
+ });
473
+ }
474
+ };
475
+ }
476
+ function countsFromRow(row) {
477
+ const revenueSum = Number(row.revenue_sum ?? 0);
478
+ return {
479
+ variant: String(row.variant),
480
+ exposures: Number(row.exposures ?? 0),
481
+ conversions: Number(row.conversions ?? 0),
482
+ revenue: revenueSum,
483
+ revenueSum,
484
+ revenueSumSq: Number(row.revenue_sum_sq ?? 0)
485
+ };
486
+ }
487
+
223
488
  // src/store.ts
224
489
  function createMemoryStore() {
225
490
  const events = [];
@@ -236,43 +501,8 @@ function createMemoryStore() {
236
501
  }
237
502
  return n;
238
503
  },
239
- async variantCounts(experiment, goal) {
240
- const earliest = /* @__PURE__ */ new Map();
241
- for (const e of events) {
242
- if (e.type !== "exposure" || e.experiment !== experiment || !e.variant) continue;
243
- const prev = earliest.get(e.visitorId);
244
- if (prev === void 0 || e.ts < prev.ts || e.ts === prev.ts && e.variant < prev.variant) {
245
- earliest.set(e.visitorId, { variant: e.variant, ts: e.ts });
246
- }
247
- }
248
- const firstExposure = /* @__PURE__ */ new Map();
249
- for (const [visitor, { variant, ts }] of earliest) {
250
- const byVisitor = firstExposure.get(variant) ?? /* @__PURE__ */ new Map();
251
- byVisitor.set(visitor, ts);
252
- firstExposure.set(variant, byVisitor);
253
- }
254
- const goalsByVisitor = /* @__PURE__ */ new Map();
255
- for (const e of events) {
256
- if (e.type !== "goal" || e.goal !== goal) continue;
257
- const list = goalsByVisitor.get(e.visitorId) ?? [];
258
- const revenue = typeof e.props?.revenue === "number" ? e.props.revenue : 0;
259
- list.push({ ts: e.ts, revenue });
260
- goalsByVisitor.set(e.visitorId, list);
261
- }
262
- const out = [];
263
- for (const [variant, byVisitor] of firstExposure) {
264
- let conversions = 0;
265
- let revenue = 0;
266
- for (const [visitor, first] of byVisitor) {
267
- const goals = (goalsByVisitor.get(visitor) ?? []).filter((g) => g.ts >= first);
268
- if (goals.length > 0) {
269
- conversions++;
270
- revenue += goals.reduce((s, g) => s + g.revenue, 0);
271
- }
272
- }
273
- out.push({ variant, exposures: byVisitor.size, conversions, revenue });
274
- }
275
- return out;
504
+ async variantCounts(experiment, goal2) {
505
+ return attributeVariants(events, experiment, goal2);
276
506
  },
277
507
  async summaries() {
278
508
  const map = /* @__PURE__ */ new Map();
@@ -296,15 +526,130 @@ function createMemoryStore() {
296
526
  }
297
527
  };
298
528
  }
529
+
530
+ // src/conformance.ts
531
+ var T = Date.UTC(2026, 0, 10, 12, 0, 0);
532
+ var DAY = 864e5;
533
+ var seq = 0;
534
+ function exposure(visitorId, variant, ts, experiment = "hero") {
535
+ seq++;
536
+ return { id: `exp_${String(seq).padStart(6, "0")}`, type: "exposure", experiment, variant, goal: null, visitorId, sessionId: `s_${visitorId}`, ts, url: null, props: null, receivedAt: ts };
537
+ }
538
+ function goal(visitorId, ts, revenue, key = "signup") {
539
+ seq++;
540
+ return { id: `goal_${String(seq).padStart(6, "0")}`, type: "goal", experiment: null, variant: null, goal: key, visitorId, sessionId: `s_${visitorId}`, ts, url: null, props: revenue === void 0 ? null : { revenue }, receivedAt: ts };
541
+ }
542
+ function counts(variant, exposures, conversions, revenueSum = 0, revenueSumSq = 0) {
543
+ return { variant, exposures, conversions, revenue: revenueSum, revenueSum, revenueSumSq };
544
+ }
545
+ var attributionConformance = [
546
+ {
547
+ name: "a visitor belongs to the variant of their earliest exposure (tie: smallest key)",
548
+ experiment: "hero",
549
+ goal: "signup",
550
+ readTimeOnly: true,
551
+ events: [
552
+ exposure("v1", "control", T + 1e3),
553
+ exposure("v1", "bold", T),
554
+ // earlier, arrives later
555
+ goal("v1", T + 5e3),
556
+ exposure("v2", "control", T),
557
+ exposure("v2", "bold", T),
558
+ exposure("v3", "bold", T),
559
+ exposure("v4", "control", T)
560
+ ],
561
+ expected: [counts("bold", 3, 1), counts("control", 1, 0)]
562
+ },
563
+ {
564
+ name: "counts unique visitors, not events",
565
+ experiment: "hero",
566
+ goal: "signup",
567
+ events: [exposure("v1", "control", T), exposure("v1", "control", T + 10), exposure("v1", "bold", T + 20), goal("v1", T + 30), goal("v1", T + 40), exposure("v2", "bold", T)],
568
+ expected: [counts("bold", 1, 0), counts("control", 1, 1)]
569
+ },
570
+ {
571
+ name: "goals well before the exposure, of other goals or from unexposed visitors do not convert",
572
+ experiment: "hero",
573
+ goal: "signup",
574
+ events: [
575
+ exposure("v1", "control", T),
576
+ goal("v1", T - ATTRIBUTION_SKEW_MS - 1e3, 9),
577
+ goal("v1", T + 1e3, 9, "other"),
578
+ exposure("other_exp", "x", T, "pricing"),
579
+ goal("nobody", T + 1e3, 9),
580
+ goal("other_exp", T + 1e3, 9)
581
+ ],
582
+ expected: [counts("control", 1, 0)]
583
+ },
584
+ {
585
+ name: `a goal up to ${ATTRIBUTION_SKEW_MS / 1e3} s before the exposure still counts (server vs browser clock)`,
586
+ experiment: "hero",
587
+ goal: "signup",
588
+ events: [
589
+ exposure("v1", "control", T),
590
+ goal("v1", T - ATTRIBUTION_SKEW_MS, 2),
591
+ exposure("v2", "bold", T),
592
+ goal("v2", T - 3e4, 3),
593
+ exposure("v3", "bold", T),
594
+ goal("v3", T - ATTRIBUTION_SKEW_MS - 1, 4)
595
+ ],
596
+ expected: [counts("bold", 2, 1, 3, 9), counts("control", 1, 1, 2, 4)]
597
+ },
598
+ {
599
+ name: `at most ${GOAL_DAILY_CAP} of one goal per visitor and UTC day`,
600
+ experiment: "hero",
601
+ goal: "signup",
602
+ events: [
603
+ exposure("v1", "control", T),
604
+ ...Array.from({ length: GOAL_DAILY_CAP + 10 }, (_, i) => goal("v1", T + 1e3 + i, 1)),
605
+ ...Array.from({ length: 3 }, (_, i) => goal("v1", T + DAY + i, 1))
606
+ ],
607
+ expected: [counts("control", 1, 1, GOAL_DAILY_CAP + 3, (GOAL_DAILY_CAP + 3) ** 2)]
608
+ },
609
+ {
610
+ name: "revenue is summed per visitor; variants report the sum and the sum of squares",
611
+ experiment: "hero",
612
+ goal: "signup",
613
+ events: [
614
+ exposure("v1", "control", T),
615
+ goal("v1", T + 1e3, 10),
616
+ goal("v1", T + 2e3, 5),
617
+ exposure("v2", "control", T),
618
+ goal("v2", T + 1e3, 20),
619
+ exposure("v3", "control", T),
620
+ goal("v3", T + 1e3, "lots"),
621
+ exposure("v4", "control", T),
622
+ exposure("v5", "bold", T),
623
+ goal("v5", T + 1e3, 2.5)
624
+ ],
625
+ expected: [counts("bold", 1, 1, 2.5, 6.25), counts("control", 4, 3, 35, 625)]
626
+ }
627
+ ];
628
+ function sortCounts(rows) {
629
+ return rows.map((r) => {
630
+ const revenueSum = r.revenueSum ?? r.revenue ?? 0;
631
+ return { variant: r.variant, exposures: r.exposures, conversions: r.conversions, revenue: revenueSum, revenueSum, revenueSumSq: r.revenueSumSq ?? 0 };
632
+ }).sort((a, b) => a.variant < b.variant ? -1 : a.variant > b.variant ? 1 : 0);
633
+ }
299
634
  export {
635
+ ATTRIBUTION_SKEW_MS,
636
+ GOAL_DAILY_CAP,
637
+ attributeVariants,
638
+ attributionConformance,
300
639
  bestOf,
640
+ countsFromRow,
301
641
  createMemoryStore,
302
642
  createSplitHubHandler,
303
643
  experimentResults,
304
644
  factorEffects,
645
+ flowExpectedShares,
305
646
  headlineFor,
647
+ resultsExperiment,
648
+ revenueOf,
649
+ sortCounts,
306
650
  statusTable,
307
651
  toNodeListener,
308
- validateBatch
652
+ validateBatch,
653
+ variantCountsSql
309
654
  };
310
655
  //# sourceMappingURL=index.js.map