@splithub/node 0.3.0 → 0.4.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/index.cjs +444 -144
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +142 -5
- package/dist/index.d.ts +142 -5
- package/dist/index.js +432 -143
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { SplitHubConfig, Experiment } from '@splithub/core';
|
|
1
|
+
import { SplitHubConfig, Experiment, Goal } from '@splithub/core';
|
|
2
2
|
import { IncomingMessage, ServerResponse } from 'node:http';
|
|
3
3
|
|
|
4
4
|
/** How far a goal may precede the exposure it converts, for clock differences between server and browser. */
|
|
@@ -23,7 +23,8 @@ interface AttributedCounts extends VariantCounts {
|
|
|
23
23
|
/** The shape of an event the rule needs. */
|
|
24
24
|
interface AttributionEvent {
|
|
25
25
|
id: string;
|
|
26
|
-
|
|
26
|
+
/** Analytics rows (`page`, `event`, `engage`, `identify`) are ignored. */
|
|
27
|
+
type: 'exposure' | 'goal' | 'page' | 'event' | 'engage' | 'identify';
|
|
27
28
|
experiment: string | null;
|
|
28
29
|
variant: string | null;
|
|
29
30
|
goal: string | null;
|
|
@@ -65,10 +66,17 @@ declare function variantCountsSql(options: VariantCountsSqlOptions): VariantCoun
|
|
|
65
66
|
/** Turns a row of `variantCountsSql` (numbers may come back as strings from pg / mysql2) into counts. */
|
|
66
67
|
declare function countsFromRow(row: Record<string, unknown>): AttributedCounts;
|
|
67
68
|
|
|
68
|
-
/**
|
|
69
|
+
/** Row types of an analytics property (`experiment` holds the property key). */
|
|
70
|
+
declare const ANALYTICS_TYPES: ReadonlySet<StoredEvent['type']>;
|
|
71
|
+
/**
|
|
72
|
+
* One row in the events table, whatever the backing database. Analytics rows reuse
|
|
73
|
+
* the columns: for `page`, `event`, `engage` and `identify`, `experiment` holds the
|
|
74
|
+
* property key and `goal` the event name (null for the others); a page's title and
|
|
75
|
+
* referrer, an engage's `{ ms, scroll }` and an identify's `{ uid, traits }` sit in `props`.
|
|
76
|
+
*/
|
|
69
77
|
interface StoredEvent {
|
|
70
78
|
id: string;
|
|
71
|
-
type: 'exposure' | 'goal';
|
|
79
|
+
type: 'exposure' | 'goal' | 'page' | 'event' | 'engage' | 'identify';
|
|
72
80
|
experiment: string | null;
|
|
73
81
|
variant: string | null;
|
|
74
82
|
goal: string | null;
|
|
@@ -118,8 +126,35 @@ interface Store {
|
|
|
118
126
|
/** Unique exposed and converted visitors per variant (any order), with per-visitor revenue sum and sum of squares. */
|
|
119
127
|
variantCounts(experiment: string, goal: string): Promise<StoreVariantCounts[]>;
|
|
120
128
|
summaries(): Promise<ExperimentSummary[]>;
|
|
129
|
+
/**
|
|
130
|
+
* Raw counts of an analytics property from `since` up to `until` (unix ms, exclusive; open-ended
|
|
131
|
+
* when missing): pageviews, events by name, unique visitors and sessions. Optional: stores
|
|
132
|
+
* without it answer 501 on `{base}/properties/:key`. SQL stores can run `propertyCountsSql`.
|
|
133
|
+
*/
|
|
134
|
+
propertyCounts?(property: string, since: number, until?: number): Promise<PropertyCounts>;
|
|
135
|
+
/** The latest raw rows of an analytics property, newest first. Optional. */
|
|
136
|
+
propertyEvents?(property: string, options: {
|
|
137
|
+
before: number;
|
|
138
|
+
limit: number;
|
|
139
|
+
}): Promise<StoredEvent[]>;
|
|
121
140
|
close?(): Promise<void> | void;
|
|
122
141
|
}
|
|
142
|
+
/** Raw counts of one analytics property; aggregated reports are SplitHub Cloud's. */
|
|
143
|
+
interface PropertyCounts {
|
|
144
|
+
pageviews: number;
|
|
145
|
+
visitors: number;
|
|
146
|
+
sessions: number;
|
|
147
|
+
/** Distinct user ids sent with identify. */
|
|
148
|
+
users: number;
|
|
149
|
+
/** Custom events (goals included) by name, most frequent first. */
|
|
150
|
+
events: Array<{
|
|
151
|
+
name: string;
|
|
152
|
+
count: number;
|
|
153
|
+
visitors: number;
|
|
154
|
+
}>;
|
|
155
|
+
}
|
|
156
|
+
/** Shared by the memory store and the tests: the counts over rows already in memory. */
|
|
157
|
+
declare function countProperty(events: Iterable<StoredEvent>, property: string, since: number, until?: number): PropertyCounts;
|
|
123
158
|
/** In-memory store for tests and quick local runs. Not persistent. */
|
|
124
159
|
declare function createMemoryStore(): Store & {
|
|
125
160
|
events: StoredEvent[];
|
|
@@ -143,6 +178,9 @@ type FetchHandler = (request: Request) => Promise<Response>;
|
|
|
143
178
|
* POST {base} → ingest an event batch
|
|
144
179
|
* GET {base}/status → all experiments with exposures, visitors and days
|
|
145
180
|
* GET {base}/results/:id → visitors, conversions, rate (and revenue) per variant
|
|
181
|
+
* GET {base}/properties → analytics properties with raw counts (`?days=30`, or `?from=&to=` UTC days)
|
|
182
|
+
* GET {base}/properties/:key → one property's raw counts
|
|
183
|
+
* GET {base}/properties/:key/events → its latest raw pageviews and events (`?before=&limit=`)
|
|
146
184
|
*
|
|
147
185
|
* Reads are raw counts; verdicts and recommendations are SplitHub Cloud's.
|
|
148
186
|
* GET {base}/health → { ok: true }
|
|
@@ -222,9 +260,85 @@ declare function rawResults(config: SplitHubConfig, store: Store, key: string, o
|
|
|
222
260
|
/** Every experiment with exposures, visitors and days; the holdout once it has visitors. */
|
|
223
261
|
declare function rawStatusTable(config: SplitHubConfig, store: Store): Promise<RawStatusRow[]>;
|
|
224
262
|
|
|
263
|
+
interface PropertyCountsSqlOptions {
|
|
264
|
+
dialect: SqlDialect;
|
|
265
|
+
/** Default `splithub_events`. */
|
|
266
|
+
table?: string;
|
|
267
|
+
/** Column holding the project name when one table serves several projects (D1 store). */
|
|
268
|
+
projectColumn?: string;
|
|
269
|
+
}
|
|
270
|
+
type Param = 'project' | 'property' | 'since' | 'until' | 'before' | 'limit';
|
|
271
|
+
interface PropertySql {
|
|
272
|
+
sql: string;
|
|
273
|
+
bind(values: Partial<Record<Param, unknown>>): unknown[];
|
|
274
|
+
}
|
|
275
|
+
/** The queries behind `propertyCounts` / `propertyEvents` for the SplitHub table layout, on SQLite, D1, Postgres and MySQL. */
|
|
276
|
+
declare function propertyCountsSql(options: PropertyCountsSqlOptions): {
|
|
277
|
+
totals: PropertySql;
|
|
278
|
+
events: PropertySql;
|
|
279
|
+
rows: PropertySql;
|
|
280
|
+
};
|
|
281
|
+
/** Rows of `propertyCountsSql().totals` and `.events` (numbers may come back as strings from pg / mysql2) as counts. */
|
|
282
|
+
declare function propertyCountsFromRows(totals: Record<string, unknown> | undefined, events: Array<Record<string, unknown>>): PropertyCounts;
|
|
283
|
+
/** A row of `propertyCountsSql().rows` (snake_case columns) as a stored event. */
|
|
284
|
+
declare function storedEventFromRow(r: Record<string, unknown>): StoredEvent;
|
|
285
|
+
interface RawPropertyReport {
|
|
286
|
+
property: string;
|
|
287
|
+
status: string;
|
|
288
|
+
name: string | null;
|
|
289
|
+
description: string | null;
|
|
290
|
+
goals: string[];
|
|
291
|
+
/** Days counted: the last `days` days, or from..to. */
|
|
292
|
+
days: number;
|
|
293
|
+
/** The UTC days counted, both inclusive. */
|
|
294
|
+
range: {
|
|
295
|
+
from: string;
|
|
296
|
+
to: string;
|
|
297
|
+
};
|
|
298
|
+
counts: PropertyCounts | null;
|
|
299
|
+
analysis: typeof ANALYSIS_UNAVAILABLE;
|
|
300
|
+
}
|
|
301
|
+
declare const PROPERTY_REPORTS_UNAVAILABLE: {
|
|
302
|
+
message: string;
|
|
303
|
+
available: false;
|
|
304
|
+
url: string;
|
|
305
|
+
};
|
|
306
|
+
/**
|
|
307
|
+
* The span a raw property read covers: `from` / `to` (YYYY-MM-DD, UTC days, both inclusive; either
|
|
308
|
+
* alone works) or the last `days` days. An error string for a malformed range.
|
|
309
|
+
*/
|
|
310
|
+
declare function rawPropertyRange(options: {
|
|
311
|
+
days?: number;
|
|
312
|
+
from?: string | null;
|
|
313
|
+
to?: string | null;
|
|
314
|
+
now?: number;
|
|
315
|
+
}): {
|
|
316
|
+
since: number;
|
|
317
|
+
until: number;
|
|
318
|
+
days: number;
|
|
319
|
+
range: {
|
|
320
|
+
from: string;
|
|
321
|
+
to: string;
|
|
322
|
+
};
|
|
323
|
+
} | string;
|
|
324
|
+
/** Raw counts of one property of the config. Null for an unknown key; throws on a malformed range (check it with `rawPropertyRange` first). */
|
|
325
|
+
declare function rawPropertyReport(config: SplitHubConfig, store: Store, key: string, options?: {
|
|
326
|
+
days?: number;
|
|
327
|
+
from?: string | null;
|
|
328
|
+
to?: string | null;
|
|
329
|
+
now?: number;
|
|
330
|
+
}): Promise<RawPropertyReport | null>;
|
|
331
|
+
|
|
332
|
+
/**
|
|
333
|
+
* A batch whose shape is wrong is refused whole (`ok: false`). Otherwise each invalid event is
|
|
334
|
+
* dropped on its own (`dropped`, with the first `errors`), so one bad goal key never takes the
|
|
335
|
+
* exposures and pageviews of the same batch down with it.
|
|
336
|
+
*/
|
|
225
337
|
type ValidationResult = {
|
|
226
338
|
ok: true;
|
|
227
339
|
events: StoredEvent[];
|
|
340
|
+
dropped: number;
|
|
341
|
+
errors: string[];
|
|
228
342
|
} | {
|
|
229
343
|
ok: false;
|
|
230
344
|
error: string;
|
|
@@ -249,4 +363,27 @@ declare const attributionConformance: ConformanceCase[];
|
|
|
249
363
|
/** Sorts by variant and keeps the compared fields, so any store's output can be `toEqual`-ed with `expected`. */
|
|
250
364
|
declare function sortCounts(rows: StoreVariantCounts[]): AttributedCounts[];
|
|
251
365
|
|
|
252
|
-
|
|
366
|
+
/** A goal an experiment is judged on, as far as deriving it from analytics rows needs. */
|
|
367
|
+
interface DerivableGoal {
|
|
368
|
+
key: string;
|
|
369
|
+
type: Goal['type'];
|
|
370
|
+
/** Event name analytics matches instead of the key. */
|
|
371
|
+
event?: string;
|
|
372
|
+
/** Pageview goals: the path pattern (`/pricing`, `/docs/*`). */
|
|
373
|
+
path?: string | null;
|
|
374
|
+
}
|
|
375
|
+
/** How close (ms) a goal row sent next to its analytics row must be to count as the same action. */
|
|
376
|
+
declare const SAME_ACTION_MS = 1000;
|
|
377
|
+
/**
|
|
378
|
+
* The goals some experiment (or the holdout) of `config` is judged on, primary or metric:
|
|
379
|
+
* the only ones analytics rows are turned into. A measured key without a declaration counts as an event goal.
|
|
380
|
+
*/
|
|
381
|
+
declare function experimentGoals(config: Pick<SplitHubConfig, 'experiments' | 'holdout' | 'goals'>): DerivableGoal[];
|
|
382
|
+
/** A derived row: marked, so a store does not count it as dropped when no experiment takes it. */
|
|
383
|
+
type DerivedGoal = StoredEvent & {
|
|
384
|
+
derived: true;
|
|
385
|
+
};
|
|
386
|
+
/** Goal rows derived from the batch's `event` and `page` rows (see the rule above). */
|
|
387
|
+
declare function goalsFromAnalytics(events: readonly StoredEvent[], goals: readonly DerivableGoal[]): DerivedGoal[];
|
|
388
|
+
|
|
389
|
+
export { ANALYSIS_UNAVAILABLE, ANALYTICS_TYPES, ATTRIBUTION_SKEW_MS, type AttributedCounts, type AttributionEvent, type ConformanceCase, type DerivableGoal, type DerivedGoal, type ExperimentSummary, type FetchHandler, GOAL_DAILY_CAP, type HandlerOptions, PROPERTY_REPORTS_UNAVAILABLE, type PropertyCounts, type PropertyCountsSqlOptions, type PropertySql, type RawMetric, type RawPropertyReport, type RawResults, type RawStatusRow, type RawVariant, SAME_ACTION_MS, type SqlDialect, type Store, type StoreVariantCounts, type StoredEvent, type ValidationResult, type VariantCounts, type VariantCountsSql, type VariantCountsSqlOptions, attributeVariants, attributionConformance, countProperty, countsFromRow, createMemoryStore, createSplitHubHandler, experimentGoals, goalsFromAnalytics, propertyCountsFromRows, propertyCountsSql, rawPropertyRange, rawPropertyReport, rawResults, rawStatusTable, resultsExperiment, revenueOf, sortCounts, storedEventFromRow, toNodeListener, validateBatch, variantCountsSql };
|