@splithub/node 0.2.3 → 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.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
- type: 'exposure' | 'goal';
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
- /** One row in the events table, whatever the backing database. */
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 }
@@ -191,6 +229,8 @@ interface RawResults {
191
229
  status: string;
192
230
  goal: string | null;
193
231
  description: string | null;
232
+ /** Human name; null = show the key. */
233
+ name: string | null;
194
234
  /** Declared order: the first variant is the control. */
195
235
  variants: RawVariant[];
196
236
  metrics?: RawMetric[];
@@ -204,6 +244,8 @@ interface RawStatusRow {
204
244
  status: string;
205
245
  goal: string | null;
206
246
  description: string | null;
247
+ /** Human name; null = show the key. */
248
+ name: string | null;
207
249
  exposures: number;
208
250
  visitors: number;
209
251
  /** Whole days with data, at least 1 once there is any; 0 without data. */
@@ -218,9 +260,85 @@ declare function rawResults(config: SplitHubConfig, store: Store, key: string, o
218
260
  /** Every experiment with exposures, visitors and days; the holdout once it has visitors. */
219
261
  declare function rawStatusTable(config: SplitHubConfig, store: Store): Promise<RawStatusRow[]>;
220
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
+ */
221
337
  type ValidationResult = {
222
338
  ok: true;
223
339
  events: StoredEvent[];
340
+ dropped: number;
341
+ errors: string[];
224
342
  } | {
225
343
  ok: false;
226
344
  error: string;
@@ -245,4 +363,27 @@ declare const attributionConformance: ConformanceCase[];
245
363
  /** Sorts by variant and keeps the compared fields, so any store's output can be `toEqual`-ed with `expected`. */
246
364
  declare function sortCounts(rows: StoreVariantCounts[]): AttributedCounts[];
247
365
 
248
- export { ANALYSIS_UNAVAILABLE, ATTRIBUTION_SKEW_MS, type AttributedCounts, type AttributionEvent, type ConformanceCase, type ExperimentSummary, type FetchHandler, GOAL_DAILY_CAP, type HandlerOptions, type RawMetric, type RawResults, type RawStatusRow, type RawVariant, type SqlDialect, type Store, type StoreVariantCounts, type StoredEvent, type VariantCounts, type VariantCountsSql, type VariantCountsSqlOptions, attributeVariants, attributionConformance, countsFromRow, createMemoryStore, createSplitHubHandler, rawResults, rawStatusTable, resultsExperiment, revenueOf, sortCounts, toNodeListener, validateBatch, variantCountsSql };
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 };