@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.cjs CHANGED
@@ -20,75 +20,219 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
20
20
  // src/index.ts
21
21
  var index_exports = {};
22
22
  __export(index_exports, {
23
+ ATTRIBUTION_SKEW_MS: () => ATTRIBUTION_SKEW_MS,
24
+ GOAL_DAILY_CAP: () => GOAL_DAILY_CAP,
25
+ attributeVariants: () => attributeVariants,
26
+ attributionConformance: () => attributionConformance,
23
27
  bestOf: () => bestOf,
28
+ countsFromRow: () => countsFromRow,
24
29
  createMemoryStore: () => createMemoryStore,
25
30
  createSplitHubHandler: () => createSplitHubHandler,
26
31
  experimentResults: () => experimentResults,
27
32
  factorEffects: () => factorEffects,
33
+ flowExpectedShares: () => flowExpectedShares,
28
34
  headlineFor: () => headlineFor,
35
+ resultsExperiment: () => resultsExperiment,
36
+ revenueOf: () => revenueOf,
37
+ sortCounts: () => sortCounts,
29
38
  statusTable: () => statusTable,
30
39
  toNodeListener: () => toNodeListener,
31
- validateBatch: () => validateBatch
40
+ validateBatch: () => validateBatch,
41
+ variantCountsSql: () => variantCountsSql
32
42
  });
33
43
  module.exports = __toCommonJS(index_exports);
34
44
 
45
+ // src/handler.ts
46
+ var import_core3 = require("@splithub/core");
47
+
35
48
  // src/results.ts
36
49
  var import_core = require("@splithub/core");
37
50
  var import_stats = require("@splithub/stats");
38
- function factorEffects(experiment, counts) {
51
+ var DAY_MS = 864e5;
52
+ function factorLevels(experiment, factor, counts2) {
53
+ return factor.levels.map((level) => {
54
+ const combos = experiment.variants.filter((v) => v.levels?.[factor.key] === level).map((v) => v.key);
55
+ const rows = counts2.filter((c) => combos.includes(c.variant));
56
+ return { variant: level, exposures: rows.reduce((s, r) => s + r.exposures, 0), conversions: rows.reduce((s, r) => s + r.conversions, 0) };
57
+ });
58
+ }
59
+ function factorPValues(experiment, counts2) {
60
+ const out = [];
61
+ for (const factor of experiment.factors ?? []) {
62
+ const perLevel = factorLevels(experiment, factor, counts2);
63
+ if (perLevel.every((l) => l.exposures > 0)) out.push(...(0, import_stats.compareVariants)(perLevel).map((c) => c.sequential.pValue));
64
+ }
65
+ return out;
66
+ }
67
+ function factorEffects(experiment, counts2, options = {}) {
39
68
  if (!experiment.factors?.length) return [];
40
- return experiment.factors.map((factor) => {
41
- const perLevel = factor.levels.map((level) => {
42
- const combos = experiment.variants.filter((v) => v.levels?.[factor.key] === level).map((v) => v.key);
43
- const rows = counts.filter((c) => combos.includes(c.variant));
44
- return { variant: level, exposures: rows.reduce((s, r) => s + r.exposures, 0), conversions: rows.reduce((s, r) => s + r.conversions, 0) };
45
- });
46
- const comparisons = perLevel.every((l) => l.exposures > 0) ? (0, import_stats.compareVariants)(perLevel) : [];
69
+ const perFactor = experiment.factors.map((factor) => {
70
+ const perLevel = factorLevels(experiment, factor, counts2);
71
+ return { factor, perLevel, comparisons: perLevel.every((l) => l.exposures > 0) ? (0, import_stats.compareVariants)(perLevel) : [] };
72
+ });
73
+ const all = perFactor.flatMap((f) => f.comparisons);
74
+ const rejected = (0, import_stats.holm)([...all.map((c) => c.sequential.pValue), ...options.familyPValues ?? []], 1 - import_stats.VERDICT_DEFAULTS.confidence);
75
+ const significant = new Map(all.map((c, i) => [c, rejected[i]]));
76
+ return perFactor.map(({ factor, perLevel, comparisons }) => {
47
77
  const levels = perLevel.map((l, i) => {
48
- const cmp = comparisons.find((c) => c.variant === l.variant);
78
+ const cmp = i === 0 ? void 0 : comparisons.find((c) => c.variant === l.variant);
49
79
  return {
50
80
  level: l.variant,
51
81
  exposures: l.exposures,
52
82
  conversions: l.conversions,
53
83
  rate: l.exposures ? l.conversions / l.exposures : 0,
54
- relativeLift: i === 0 ? null : cmp?.relativeLift ?? null,
55
- pValue: i === 0 ? null : cmp?.pValue ?? null,
56
- significant: Boolean(cmp?.significant)
84
+ relativeLift: cmp?.relativeLift ?? null,
85
+ pValue: cmp?.pValue ?? null,
86
+ sequentialPValue: cmp?.sequential.pValue ?? null,
87
+ probabilityToBeat: cmp?.probabilityToBeat ?? null,
88
+ significant: cmp ? Boolean(significant.get(cmp)) : false
57
89
  };
58
90
  });
59
91
  const winners = levels.filter((l) => l.significant && (l.relativeLift ?? 0) > 0).sort((a, b) => (b.relativeLift ?? 0) - (a.relativeLift ?? 0));
60
92
  return { key: factor.key, levels, best: winners[0]?.level ?? null };
61
93
  });
62
94
  }
63
- async function experimentResults(config, store, key) {
64
- const experiment = (0, import_core.getExperiment)(config, key);
65
- if (!experiment) return null;
66
- const goal = experiment.goal;
67
- const observed = goal ? await store.variantCounts(key, goal) : [];
68
- const counts = experiment.variants.map((v) => {
95
+ var sum = (xs) => xs.reduce((s, x) => s + x, 0);
96
+ var sameShares = (a, b) => {
97
+ const sa = sum(a);
98
+ const sb = sum(b);
99
+ return a.every((x, i) => Math.abs(x / sa - b[i] / sb) < 1e-9);
100
+ };
101
+ function flowExpectedShares(experiment, flow) {
102
+ const keys = experiment.variants.map((v) => v.key);
103
+ const zero = () => new Array(keys.length).fill(0);
104
+ const memo = /* @__PURE__ */ new Map();
105
+ const walk = (id, depth) => {
106
+ if (!id) return { mass: zero(), known: true };
107
+ if (depth > 64) return "unknown";
108
+ const cached = memo.get(id);
109
+ if (cached) return cached;
110
+ const node = flow.nodes[id];
111
+ let out;
112
+ if (!node || node.type === "skip") out = { mass: zero(), known: true };
113
+ else if (node.type === "variant") {
114
+ const mass = zero();
115
+ const i = keys.indexOf(node.variant);
116
+ if (i >= 0) mass[i] = 1;
117
+ out = { mass, known: true };
118
+ } else {
119
+ 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) }];
120
+ const branches = [];
121
+ for (const b of raw) if (b.reach !== "unknown") branches.push({ weight: b.weight, reach: b.reach });
122
+ const live = branches.filter((b) => sum(b.reach.mass) > 0);
123
+ if (branches.length < raw.length) out = "unknown";
124
+ else if (node.type === "split" && branches.every((b) => b.reach.known)) {
125
+ const total = sum(branches.map((b) => b.weight));
126
+ const mass = zero();
127
+ for (const b of branches) b.reach.mass.forEach((m, i) => mass[i] += b.weight / total * m);
128
+ out = { mass, known: true };
129
+ } else if (live.length === 0) out = { mass: zero(), known: true };
130
+ else if (live.every((b) => sameShares(b.reach.mass, live[0].reach.mass))) {
131
+ const ref = live[0].reach.mass;
132
+ out = { mass: ref.map((m) => m / sum(ref)), known: false };
133
+ } else out = "unknown";
134
+ }
135
+ memo.set(id, out);
136
+ return out;
137
+ };
138
+ const reach = walk(flow.start, 0);
139
+ if (reach === "unknown" || sum(reach.mass) <= 0) return null;
140
+ return reach.mass;
141
+ }
142
+ function resultsExperiment(config, key) {
143
+ return (0, import_core.getExperiment)(config, key) ?? (key === import_core.HOLDOUT_KEY ? (0, import_core.holdoutExperiment)(config) : null);
144
+ }
145
+ function alignCounts(experiment, observed) {
146
+ return experiment.variants.map((v) => {
69
147
  const row = observed.find((o) => o.variant === v.key);
70
- return { variant: v.key, exposures: row?.exposures ?? 0, conversions: row?.conversions ?? 0, revenue: row?.revenue ?? 0 };
148
+ return {
149
+ variant: v.key,
150
+ exposures: row?.exposures ?? 0,
151
+ conversions: row?.conversions ?? 0,
152
+ revenue: row?.revenue ?? row?.revenueSum ?? 0,
153
+ ...row?.revenueSum !== void 0 ? { revenueSum: row.revenueSum } : {},
154
+ ...row?.revenueSumSq !== void 0 ? { revenueSumSq: row.revenueSumSq } : {}
155
+ };
71
156
  });
72
- const verdict = goal ? (0, import_stats.computeVerdict)(key, counts, { expectedWeights: experiment.variants.map((v) => v.weight) }) : { ...(0, import_stats.computeVerdict)(key, [], {}), message: "No goal configured for this experiment; add `goal` in splithub.config.ts." };
73
- return { experiment: key, kind: experiment.kind, status: experiment.status, goal, description: experiment.description, verdict, ...experiment.kind === "mvt" && goal ? { factors: factorEffects(experiment, counts) } : {} };
157
+ }
158
+ async function metricInputs(experiment, store) {
159
+ const m = experiment.metrics;
160
+ if (!m) return [];
161
+ const list = [
162
+ ...m.secondary.map((metric) => ({ metric, role: "secondary" })),
163
+ ...m.guardrails.map((g) => ({ metric: g.goal, role: "guardrail", worse: g.worse }))
164
+ ];
165
+ return Promise.all(list.map(async (x) => ({ ...x, counts: alignCounts(experiment, await store.variantCounts(experiment.key, x.metric)) })));
166
+ }
167
+ async function experimentResults(config, store, key, options = {}) {
168
+ const experiment = resultsExperiment(config, key);
169
+ if (!experiment) return null;
170
+ const goal2 = experiment.goal;
171
+ const observed = goal2 ? await store.variantCounts(key, goal2) : [];
172
+ const counts2 = alignCounts(experiment, observed);
173
+ const metrics = goal2 ? await metricInputs(experiment, store) : [];
174
+ const now = options.now ?? /* @__PURE__ */ new Date();
175
+ const summary = options.summary !== void 0 ? options.summary : goal2 ? (await store.summaries()).find((s) => s.experiment === key) ?? null : null;
176
+ const span = summary?.firstExposureAt != null && summary.lastExposureAt != null ? (summary.lastExposureAt - summary.firstExposureAt) / DAY_MS : void 0;
177
+ const days = options.days ?? span;
178
+ const visitors = counts2.reduce((s, c) => s + c.exposures, 0);
179
+ const visitorsPerDay = options.visitorsPerDay ?? (days !== void 0 && days >= 1 / 24 && visitors > 0 ? visitors / days : null);
180
+ let expected = { expectedWeights: experiment.variants.map((v) => v.weight) };
181
+ if (experiment.flow) {
182
+ const shares = flowExpectedShares(experiment, experiment.flow);
183
+ expected = shares ? { expectedWeights: shares } : { skipSrm: "Split check skipped: targeting conditions decide which variant a visitor reaches, so the expected split depends on who visits." };
184
+ }
185
+ const isMvt = experiment.kind === "mvt" && Boolean(goal2);
186
+ const familyPValues = isMvt ? factorPValues(experiment, counts2) : void 0;
187
+ const limits = { ...experiment.minDays !== void 0 ? { minDays: experiment.minDays } : {}, ...experiment.goodSample !== void 0 ? { goodSample: experiment.goodSample } : {} };
188
+ const verdict = goal2 ? (0, import_stats.computeVerdict)(key, counts2, { ...expected, days, familyPValues, now, ...limits, ...metrics.length ? { metrics } : {} }) : { ...(0, import_stats.computeVerdict)(key, [], { now, ...limits }), message: "No goal configured for this experiment; add `goal` in splithub.config.ts." };
189
+ const factors = isMvt ? factorEffects(experiment, counts2, { familyPValues: verdict.comparisons.map((c) => c.sequential.pValue) }) : void 0;
190
+ const revenue = goal2 ? revenueResult(counts2, Boolean(config.goals.find((g) => g.key === goal2)?.revenue)) : void 0;
191
+ return {
192
+ experiment: key,
193
+ kind: experiment.kind,
194
+ status: experiment.status,
195
+ goal: goal2,
196
+ description: experiment.description,
197
+ verdict,
198
+ daysToVerdict: goal2 ? (0, import_stats.estimateDaysToVerdict)(verdict, visitorsPerDay) : null,
199
+ visitorsPerDay: visitorsPerDay === null ? null : Math.round(visitorsPerDay * 10) / 10,
200
+ ...factors ? { factors } : {},
201
+ ...revenue ? { revenue } : {}
202
+ };
203
+ }
204
+ function revenueResult(counts2, goalHasRevenue) {
205
+ if (!counts2.every((c) => typeof c.revenueSumSq === "number")) return void 0;
206
+ const rows = counts2.map((c) => ({ variant: c.variant, n: c.exposures, sum: c.revenueSum ?? c.revenue ?? 0, sumSq: c.revenueSumSq ?? 0 }));
207
+ if (!goalHasRevenue && rows.every((r) => r.sum === 0)) return void 0;
208
+ return {
209
+ variants: rows.map((r) => ({ variant: r.variant, visitors: r.n, revenue: r.sum, perVisitor: r.n > 0 ? r.sum / r.n : 0 })),
210
+ comparisons: (0, import_stats.compareMeans)(rows)
211
+ };
74
212
  }
75
213
  async function statusTable(config, store) {
76
214
  const summaries = await store.summaries();
77
215
  const byKey = new Map(summaries.map((s) => [s.experiment, s]));
78
216
  const rows = [];
79
- for (const exp of config.experiments) {
217
+ const holdout = (0, import_core.holdoutExperiment)(config);
218
+ const all = holdout && byKey.has(import_core.HOLDOUT_KEY) ? [...config.experiments, holdout] : config.experiments;
219
+ for (const exp of all) {
80
220
  const s = byKey.get(exp.key);
81
221
  const days = s?.firstExposureAt && s.lastExposureAt ? Math.max(1, Math.ceil((s.lastExposureAt - s.firstExposureAt) / 864e5)) : 0;
82
222
  let verdict = null;
83
223
  let headline = null;
84
224
  let best = null;
225
+ let sample = null;
226
+ let stars = null;
85
227
  if (exp.goal && s) {
86
- const r = await experimentResults(config, store, exp.key);
228
+ const r = await experimentResults(config, store, exp.key, { summary: s });
87
229
  verdict = r?.verdict.status ?? null;
88
230
  headline = r ? headlineFor(r.verdict) : null;
89
231
  best = r ? bestOf(r.verdict) : null;
232
+ sample = r?.verdict.sample.quality ?? null;
233
+ stars = r?.verdict.sample.stars ?? null;
90
234
  }
91
- 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 });
235
+ 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 });
92
236
  }
93
237
  return rows;
94
238
  }
@@ -109,6 +253,8 @@ function headlineFor(v) {
109
253
  return best ? `#${best.index} ${lift} (too early)` : "too early";
110
254
  case "srm_detected":
111
255
  return "SRM! check setup";
256
+ case "guardrail_breached":
257
+ return `guardrail hit: ${v.guardrailBreached?.[0]?.metric ?? "?"}`;
112
258
  case "no_significant_difference":
113
259
  return "no difference";
114
260
  default:
@@ -117,6 +263,7 @@ function headlineFor(v) {
117
263
  }
118
264
 
119
265
  // src/validate.ts
266
+ var import_core2 = require("@splithub/core");
120
267
  var ID = /^[a-z0-9_-]{8,64}$/i;
121
268
  var KEY = /^[a-z0-9][a-z0-9_-]{0,63}$/;
122
269
  var MAX_EVENTS = 500;
@@ -147,7 +294,7 @@ function normalize(e, now) {
147
294
  const ts = Math.abs(e.ts - now) > MAX_SKEW_MS ? now : Math.round(e.ts);
148
295
  const url = typeof e.url === "string" ? e.url.slice(0, 512) : null;
149
296
  if (e.type === "exposure") {
150
- if (typeof e.exp !== "string" || !KEY.test(e.exp)) return "exposure.exp is invalid";
297
+ if (typeof e.exp !== "string" || !(KEY.test(e.exp) || e.exp === import_core2.HOLDOUT_KEY)) return "exposure.exp is invalid";
151
298
  if (typeof e.var !== "string" || !KEY.test(e.var)) return "exposure.var is invalid";
152
299
  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 };
153
300
  }
@@ -165,6 +312,8 @@ function normalize(e, now) {
165
312
  }
166
313
 
167
314
  // src/handler.ts
315
+ var isBotUserAgent = (ua) => (0, import_core3.isCrawler)(ua);
316
+ var visitorUserAgent = (request) => request.headers.get("x-splithub-ua") ?? request.headers.get("user-agent");
168
317
  function createSplitHubHandler(options) {
169
318
  const { config, store } = options;
170
319
  const corsHeaders = (request) => {
@@ -199,6 +348,7 @@ function createSplitHubHandler(options) {
199
348
  }
200
349
  const result = validateBatch(body, config.project);
201
350
  if (!result.ok) return json(request, { error: result.error }, 400);
351
+ if (isBotUserAgent(visitorUserAgent(request))) return json(request, { ok: true, received: result.events.length, inserted: 0 }, 202);
202
352
  const inserted = await store.insertEvents(result.events);
203
353
  return json(request, { ok: true, received: result.events.length, inserted }, 202);
204
354
  }
@@ -249,11 +399,136 @@ async function toRequest(req) {
249
399
  if (method !== "GET" && method !== "HEAD") {
250
400
  const chunks = [];
251
401
  for await (const chunk of req) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
252
- body = Buffer.concat(chunks);
402
+ const all = Buffer.concat(chunks);
403
+ const copy = new Uint8Array(all.byteLength);
404
+ copy.set(all);
405
+ body = copy.buffer;
253
406
  }
254
407
  return new Request(url, { method, headers, body });
255
408
  }
256
409
 
410
+ // src/attribution.ts
411
+ var ATTRIBUTION_SKEW_MS = 6e4;
412
+ var GOAL_DAILY_CAP = 50;
413
+ var DAY_MS2 = 864e5;
414
+ function revenueOf(props) {
415
+ const v = props?.revenue;
416
+ return typeof v === "number" && Number.isFinite(v) ? v : 0;
417
+ }
418
+ function attributeVariants(events, experiment, goal2) {
419
+ const first = /* @__PURE__ */ new Map();
420
+ const goals = /* @__PURE__ */ new Map();
421
+ for (const e of events) {
422
+ if (e.type === "exposure") {
423
+ if (e.experiment !== experiment || !e.variant) continue;
424
+ const prev = first.get(e.visitorId);
425
+ 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 });
426
+ } else if (e.goal === goal2) {
427
+ const key = `${e.visitorId}\0${e.ts - e.ts % DAY_MS2}`;
428
+ const list = goals.get(key) ?? [];
429
+ list.push(e);
430
+ goals.set(key, list);
431
+ }
432
+ }
433
+ const counted = /* @__PURE__ */ new Map();
434
+ const revenueByVisitor = /* @__PURE__ */ new Map();
435
+ for (const list of goals.values()) {
436
+ list.sort((a, b) => a.ts - b.ts || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
437
+ for (const g of list.slice(0, GOAL_DAILY_CAP)) {
438
+ (counted.get(g.visitorId) ?? counted.set(g.visitorId, []).get(g.visitorId)).push(g.ts);
439
+ (revenueByVisitor.get(g.visitorId) ?? revenueByVisitor.set(g.visitorId, []).get(g.visitorId)).push(revenueOf(g.props));
440
+ }
441
+ }
442
+ const out = /* @__PURE__ */ new Map();
443
+ for (const [visitor, { variant, ts }] of first) {
444
+ const row = out.get(variant) ?? { variant, exposures: 0, conversions: 0, revenue: 0, revenueSum: 0, revenueSumSq: 0 };
445
+ row.exposures++;
446
+ const times = counted.get(visitor) ?? [];
447
+ const revenues = revenueByVisitor.get(visitor) ?? [];
448
+ let converted = false;
449
+ let revenue = 0;
450
+ times.forEach((t, i) => {
451
+ if (t < ts - ATTRIBUTION_SKEW_MS) return;
452
+ converted = true;
453
+ revenue += revenues[i];
454
+ });
455
+ if (converted) {
456
+ row.conversions++;
457
+ row.revenueSum += revenue;
458
+ row.revenueSumSq += revenue * revenue;
459
+ row.revenue = row.revenueSum;
460
+ }
461
+ out.set(variant, row);
462
+ }
463
+ return [...out.values()];
464
+ }
465
+ var IDENT = /^[a-z_][a-z0-9_]*$/i;
466
+ function revenueExpr(dialect, alias) {
467
+ if (dialect === "postgres") return `CASE WHEN jsonb_typeof(${alias}.props::jsonb -> 'revenue') = 'number' THEN (${alias}.props::jsonb ->> 'revenue')::float8 ELSE 0 END`;
468
+ 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`;
469
+ return `CASE WHEN json_type(${alias}.props, '$.revenue') IN ('integer', 'real') THEN json_extract(${alias}.props, '$.revenue') ELSE 0 END`;
470
+ }
471
+ function variantCountsSql(options) {
472
+ const { dialect } = options;
473
+ const t = options.table ?? "splithub_events";
474
+ if (!IDENT.test(t)) throw new Error("[splithub] invalid table name");
475
+ if (options.projectColumn !== void 0 && !IDENT.test(options.projectColumn)) throw new Error("[splithub] invalid column name");
476
+ const params = [];
477
+ const p = (name) => {
478
+ if (dialect === "postgres") {
479
+ const i = params.indexOf(name);
480
+ if (i >= 0) return `$${i + 1}`;
481
+ params.push(name);
482
+ return `$${params.length}`;
483
+ }
484
+ params.push(name);
485
+ return "?";
486
+ };
487
+ const proj = (alias) => options.projectColumn ? `${alias}.${options.projectColumn} = ${p("project")} AND ` : "";
488
+ 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`;
489
+ const fe = `SELECT MIN(e.variant) AS variant, fv.visitor_id, fv.first_ts
490
+ FROM (${fv}) fv
491
+ 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
492
+ GROUP BY fv.visitor_id, fv.first_ts`;
493
+ 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}
494
+ AND (SELECT COUNT(*) FROM ${t} g2
495
+ WHERE ${proj("g2")}g2.type = 'goal' AND g2.goal = g.goal AND g2.visitor_id = g.visitor_id
496
+ 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}`;
497
+ const sql = `SELECT v.variant AS variant, COUNT(*) AS exposures, SUM(v.converted) AS conversions,
498
+ COALESCE(SUM(v.revenue), 0) AS revenue_sum, COALESCE(SUM(v.revenue * v.revenue), 0) AS revenue_sum_sq
499
+ FROM (
500
+ SELECT fe.variant, fe.visitor_id,
501
+ CASE WHEN COUNT(g.id) > 0 THEN 1 ELSE 0 END AS converted,
502
+ COALESCE(SUM(${revenueExpr(dialect, "g")}), 0) AS revenue
503
+ FROM (${fe}) fe
504
+ LEFT JOIN ${t} g ON ${goalJoin}
505
+ GROUP BY fe.variant, fe.visitor_id
506
+ ) v
507
+ GROUP BY v.variant`;
508
+ return {
509
+ sql,
510
+ params,
511
+ bind(values) {
512
+ return params.map((name) => {
513
+ const v = values[name];
514
+ if (v === void 0) throw new Error(`[splithub] missing "${name}" for the attribution query`);
515
+ return v;
516
+ });
517
+ }
518
+ };
519
+ }
520
+ function countsFromRow(row) {
521
+ const revenueSum = Number(row.revenue_sum ?? 0);
522
+ return {
523
+ variant: String(row.variant),
524
+ exposures: Number(row.exposures ?? 0),
525
+ conversions: Number(row.conversions ?? 0),
526
+ revenue: revenueSum,
527
+ revenueSum,
528
+ revenueSumSq: Number(row.revenue_sum_sq ?? 0)
529
+ };
530
+ }
531
+
257
532
  // src/store.ts
258
533
  function createMemoryStore() {
259
534
  const events = [];
@@ -270,43 +545,8 @@ function createMemoryStore() {
270
545
  }
271
546
  return n;
272
547
  },
273
- async variantCounts(experiment, goal) {
274
- const earliest = /* @__PURE__ */ new Map();
275
- for (const e of events) {
276
- if (e.type !== "exposure" || e.experiment !== experiment || !e.variant) continue;
277
- const prev = earliest.get(e.visitorId);
278
- if (prev === void 0 || e.ts < prev.ts || e.ts === prev.ts && e.variant < prev.variant) {
279
- earliest.set(e.visitorId, { variant: e.variant, ts: e.ts });
280
- }
281
- }
282
- const firstExposure = /* @__PURE__ */ new Map();
283
- for (const [visitor, { variant, ts }] of earliest) {
284
- const byVisitor = firstExposure.get(variant) ?? /* @__PURE__ */ new Map();
285
- byVisitor.set(visitor, ts);
286
- firstExposure.set(variant, byVisitor);
287
- }
288
- const goalsByVisitor = /* @__PURE__ */ new Map();
289
- for (const e of events) {
290
- if (e.type !== "goal" || e.goal !== goal) continue;
291
- const list = goalsByVisitor.get(e.visitorId) ?? [];
292
- const revenue = typeof e.props?.revenue === "number" ? e.props.revenue : 0;
293
- list.push({ ts: e.ts, revenue });
294
- goalsByVisitor.set(e.visitorId, list);
295
- }
296
- const out = [];
297
- for (const [variant, byVisitor] of firstExposure) {
298
- let conversions = 0;
299
- let revenue = 0;
300
- for (const [visitor, first] of byVisitor) {
301
- const goals = (goalsByVisitor.get(visitor) ?? []).filter((g) => g.ts >= first);
302
- if (goals.length > 0) {
303
- conversions++;
304
- revenue += goals.reduce((s, g) => s + g.revenue, 0);
305
- }
306
- }
307
- out.push({ variant, exposures: byVisitor.size, conversions, revenue });
308
- }
309
- return out;
548
+ async variantCounts(experiment, goal2) {
549
+ return attributeVariants(events, experiment, goal2);
310
550
  },
311
551
  async summaries() {
312
552
  const map = /* @__PURE__ */ new Map();
@@ -330,16 +570,131 @@ function createMemoryStore() {
330
570
  }
331
571
  };
332
572
  }
573
+
574
+ // src/conformance.ts
575
+ var T = Date.UTC(2026, 0, 10, 12, 0, 0);
576
+ var DAY = 864e5;
577
+ var seq = 0;
578
+ function exposure(visitorId, variant, ts, experiment = "hero") {
579
+ seq++;
580
+ 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 };
581
+ }
582
+ function goal(visitorId, ts, revenue, key = "signup") {
583
+ seq++;
584
+ 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 };
585
+ }
586
+ function counts(variant, exposures, conversions, revenueSum = 0, revenueSumSq = 0) {
587
+ return { variant, exposures, conversions, revenue: revenueSum, revenueSum, revenueSumSq };
588
+ }
589
+ var attributionConformance = [
590
+ {
591
+ name: "a visitor belongs to the variant of their earliest exposure (tie: smallest key)",
592
+ experiment: "hero",
593
+ goal: "signup",
594
+ readTimeOnly: true,
595
+ events: [
596
+ exposure("v1", "control", T + 1e3),
597
+ exposure("v1", "bold", T),
598
+ // earlier, arrives later
599
+ goal("v1", T + 5e3),
600
+ exposure("v2", "control", T),
601
+ exposure("v2", "bold", T),
602
+ exposure("v3", "bold", T),
603
+ exposure("v4", "control", T)
604
+ ],
605
+ expected: [counts("bold", 3, 1), counts("control", 1, 0)]
606
+ },
607
+ {
608
+ name: "counts unique visitors, not events",
609
+ experiment: "hero",
610
+ goal: "signup",
611
+ 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)],
612
+ expected: [counts("bold", 1, 0), counts("control", 1, 1)]
613
+ },
614
+ {
615
+ name: "goals well before the exposure, of other goals or from unexposed visitors do not convert",
616
+ experiment: "hero",
617
+ goal: "signup",
618
+ events: [
619
+ exposure("v1", "control", T),
620
+ goal("v1", T - ATTRIBUTION_SKEW_MS - 1e3, 9),
621
+ goal("v1", T + 1e3, 9, "other"),
622
+ exposure("other_exp", "x", T, "pricing"),
623
+ goal("nobody", T + 1e3, 9),
624
+ goal("other_exp", T + 1e3, 9)
625
+ ],
626
+ expected: [counts("control", 1, 0)]
627
+ },
628
+ {
629
+ name: `a goal up to ${ATTRIBUTION_SKEW_MS / 1e3} s before the exposure still counts (server vs browser clock)`,
630
+ experiment: "hero",
631
+ goal: "signup",
632
+ events: [
633
+ exposure("v1", "control", T),
634
+ goal("v1", T - ATTRIBUTION_SKEW_MS, 2),
635
+ exposure("v2", "bold", T),
636
+ goal("v2", T - 3e4, 3),
637
+ exposure("v3", "bold", T),
638
+ goal("v3", T - ATTRIBUTION_SKEW_MS - 1, 4)
639
+ ],
640
+ expected: [counts("bold", 2, 1, 3, 9), counts("control", 1, 1, 2, 4)]
641
+ },
642
+ {
643
+ name: `at most ${GOAL_DAILY_CAP} of one goal per visitor and UTC day`,
644
+ experiment: "hero",
645
+ goal: "signup",
646
+ events: [
647
+ exposure("v1", "control", T),
648
+ ...Array.from({ length: GOAL_DAILY_CAP + 10 }, (_, i) => goal("v1", T + 1e3 + i, 1)),
649
+ ...Array.from({ length: 3 }, (_, i) => goal("v1", T + DAY + i, 1))
650
+ ],
651
+ expected: [counts("control", 1, 1, GOAL_DAILY_CAP + 3, (GOAL_DAILY_CAP + 3) ** 2)]
652
+ },
653
+ {
654
+ name: "revenue is summed per visitor; variants report the sum and the sum of squares",
655
+ experiment: "hero",
656
+ goal: "signup",
657
+ events: [
658
+ exposure("v1", "control", T),
659
+ goal("v1", T + 1e3, 10),
660
+ goal("v1", T + 2e3, 5),
661
+ exposure("v2", "control", T),
662
+ goal("v2", T + 1e3, 20),
663
+ exposure("v3", "control", T),
664
+ goal("v3", T + 1e3, "lots"),
665
+ exposure("v4", "control", T),
666
+ exposure("v5", "bold", T),
667
+ goal("v5", T + 1e3, 2.5)
668
+ ],
669
+ expected: [counts("bold", 1, 1, 2.5, 6.25), counts("control", 4, 3, 35, 625)]
670
+ }
671
+ ];
672
+ function sortCounts(rows) {
673
+ return rows.map((r) => {
674
+ const revenueSum = r.revenueSum ?? r.revenue ?? 0;
675
+ return { variant: r.variant, exposures: r.exposures, conversions: r.conversions, revenue: revenueSum, revenueSum, revenueSumSq: r.revenueSumSq ?? 0 };
676
+ }).sort((a, b) => a.variant < b.variant ? -1 : a.variant > b.variant ? 1 : 0);
677
+ }
333
678
  // Annotate the CommonJS export names for ESM import in node:
334
679
  0 && (module.exports = {
680
+ ATTRIBUTION_SKEW_MS,
681
+ GOAL_DAILY_CAP,
682
+ attributeVariants,
683
+ attributionConformance,
335
684
  bestOf,
685
+ countsFromRow,
336
686
  createMemoryStore,
337
687
  createSplitHubHandler,
338
688
  experimentResults,
339
689
  factorEffects,
690
+ flowExpectedShares,
340
691
  headlineFor,
692
+ resultsExperiment,
693
+ revenueOf,
694
+ sortCounts,
341
695
  statusTable,
342
696
  toNodeListener,
343
- validateBatch
697
+ validateBatch,
698
+ variantCountsSql
344
699
  });
345
700
  //# sourceMappingURL=index.cjs.map