@splithub/core 0.3.0 → 0.4.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.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { S as SplitHubConfigInput, a as SplitHubConfig, E as Experiment, V as Variant, F as Factor, T as TargetingContext, A as Assignment, b as Flow, c as TargetCondition, d as TargetField, e as TargetOp, f as EventBatch, g as SplitHubEvent, h as ExperimentStatus, G as Goal, H as Holdout } from './types-DlycK6Py.cjs';
2
- export { n as ComponentExperimentInput, C as ComponentVariantInput, l as ExperimentBase, q as ExperimentInput, i as ExperimentKind, t as ExperimentMetrics, u as ExposureEvent, k as FlowNode, v as GoalEvent, r as GoalInput, m as GuardrailInput, M as MvtExperimentInput, p as RedirectExperimentInput, R as RedirectVariantInput, s as StorageInput, o as ValueExperimentInput, j as ValueVariantInput } from './types-DlycK6Py.cjs';
1
+ import { S as SplitHubConfigInput, a as SplitHubConfig, E as Experiment, V as Variant, F as Factor, P as PropertyInput, G as Goal, b as Property, T as TargetingContext, A as Assignment, c as Flow, d as TargetCondition, e as TargetField, f as TargetOp, g as EventBatch, h as SplitHubEvent, i as ExperimentStatus, j as PropertyStatus, H as Holdout } from './types-DKx9MXeC.cjs';
2
+ export { p as ComponentExperimentInput, C as ComponentVariantInput, D as EngageEvent, n as ExperimentBase, s as ExperimentInput, k as ExperimentKind, w as ExperimentMetrics, x as ExposureEvent, m as FlowNode, y as GoalEvent, u as GoalInput, t as GoalLabels, o as GuardrailInput, I as IdentifyEvent, M as MvtExperimentInput, z as PageEvent, r as RedirectExperimentInput, R as RedirectVariantInput, v as StorageInput, B as TrackEvent, q as ValueExperimentInput, l as ValueVariantInput } from './types-DKx9MXeC.cjs';
3
3
 
4
4
  declare class ConfigError extends Error {
5
5
  constructor(message: string);
@@ -20,6 +20,26 @@ declare function mvtVariants(expKey: string, factors: Record<string, Record<stri
20
20
  declare const HOLDOUT_KEY = "__holdout";
21
21
  /** Buckets per layer: an experiment's `layer.range` is a slice of 0..LAYER_BUCKETS. */
22
22
  declare const LAYER_BUCKETS = 100;
23
+ /** Analytics property ids, like every key: lowercase letters, digits, - and _. Generated ones look like `sh-x1h78w`. */
24
+ declare const PROPERTY_KEY_PATTERN: RegExp;
25
+ /** A new property id: `sh-` and six letters or digits without look-alikes (0/o, 1/l/i). */
26
+ declare function newPropertyId(): string;
27
+ /** Custom event names: letters, digits, spaces and `_ . : / -`, up to 64 characters (`signup`, `Video Played`). */
28
+ declare const EVENT_NAME_PATTERN: RegExp;
29
+ /**
30
+ * The goal key of an event name: `Video Played` → `video-played`, `signup` → `signup`.
31
+ * Lowercase, every run of other characters becomes `-`. Empty when nothing usable is left;
32
+ * check the result against `PROPERTY_KEY_PATTERN` before sending it as a key.
33
+ */
34
+ declare function eventKey(name: string): string;
35
+ /**
36
+ * The goal key an event name counts as: a declared goal key itself, the goal whose `event`
37
+ * is that name, or the name's slug (`eventKey`). Null when the name has no usable key.
38
+ */
39
+ declare function goalKeyFor(goals: ReadonlyArray<Pick<Goal, 'key' | 'event'>>, name: string): string | null;
40
+ declare function normalizeProperty(key: string, input: PropertyInput, goals: Goal[]): Property;
41
+ /** The property with this id, or null. Events only go to a property named explicitly, never to a guess. */
42
+ declare function pickProperty(config: Pick<SplitHubConfig, 'properties'>, key?: string | null): Property | null;
23
43
  /**
24
44
  * Validate and normalize a config. Call it once in `splithub.config.ts`:
25
45
  *
@@ -102,6 +122,9 @@ declare function resetDevNotes(): void;
102
122
  /** Explain an assignment that may surprise a developer: a draft, a paused test, a test outside its dates. */
103
123
  declare function explainAssignment(experiment: Experiment | undefined, a: Assignment): void;
104
124
 
125
+ /** Forget every claim (tests). */
126
+ declare function resetAnalyticsClaims(): void;
127
+
105
128
  /**
106
129
  * MurmurHash3 (32-bit, x86). Deterministic across browser, Node and edge
107
130
  * runtimes, with a uniform distribution suitable for bucketing.
@@ -182,6 +205,12 @@ declare function matchPath(pattern: string, pathname: string): boolean;
182
205
  * `?utm_source` survives) and the current hash kept unless `to` has one.
183
206
  */
184
207
  declare function redirectTarget(to: string, currentHref: string): URL;
208
+ /**
209
+ * Where a visit came from, as an exposure carries it: the referrer's origin only (never its path
210
+ * or query), `''` for a visit with no referrer (direct), and `undefined` when it says nothing
211
+ * about the source: a link from the same site, or a value that is not a URL.
212
+ */
213
+ declare function referrerOrigin(referrer: string | null | undefined, siteHost: string | null | undefined): string | undefined;
185
214
 
186
215
  interface RedirectDecision {
187
216
  experiment: string;
@@ -284,6 +313,12 @@ interface RemoteOverrides {
284
313
  added?: Experiment[];
285
314
  /** Goals declared in the dashboard (hosted config). */
286
315
  goals?: Goal[];
316
+ /** Analytics property status set from the dashboard or the CLI, by key. */
317
+ properties?: Record<string, {
318
+ status?: PropertyStatus;
319
+ }>;
320
+ /** Analytics properties created in the dashboard that are not in the config file. */
321
+ addedProperties?: Property[];
287
322
  /**
288
323
  * Holdout and layer seeds of the hosted config (sites on sh.js have no config file).
289
324
  * A config file's own `holdout` / `layers` win over these.
@@ -346,6 +381,11 @@ interface ClientOptions {
346
381
  ttlMs?: number;
347
382
  /** First visit (nothing cached): how long to wait for the overrides before deciding from the file. Default 400 ms; 0 decides at once. */
348
383
  waitMs?: number;
384
+ /**
385
+ * Overrides still on their way (the drop-in script stops waiting for experiments before they arrive).
386
+ * Analytics events for a property they may declare wait for them, up to 5 s.
387
+ */
388
+ arriving?: Promise<RemoteOverrides | null>;
349
389
  };
350
390
  /**
351
391
  * Visitor context for targeting (country, device, UTM ...). In the browser it
@@ -353,6 +393,21 @@ interface ClientOptions {
353
393
  * overrides JSON); on the server pass what you know from the request.
354
394
  */
355
395
  context?: TargetingContext;
396
+ /**
397
+ * Analytics property that receives pageviews and events: its id (`sh-x1h78w`), from
398
+ * `properties` in the config or from the dashboard. Without it no analytics events are sent.
399
+ */
400
+ property?: string | false;
401
+ /**
402
+ * Single-page apps: after the first pageview(), report every client-side navigation
403
+ * (history.pushState / replaceState / back) as a pageview too. Default true in the browser.
404
+ */
405
+ trackNavigation?: boolean;
406
+ /**
407
+ * Hash routers (`/#/pricing`): report the route after `#` as the page. Default: only when the
408
+ * path is `/` and the hash starts with `#/`; `false` never, `true` on any path.
409
+ */
410
+ trackHash?: boolean;
356
411
  onError?: (error: unknown) => void;
357
412
  }
358
413
  interface SplitHubClient {
@@ -379,9 +434,22 @@ interface SplitHubClient {
379
434
  value<T = unknown>(experimentKey: string): T;
380
435
  /** Record an exposure explicitly (the React components call this on mount). */
381
436
  exposure(experimentKey: string): void;
382
- track(goal: string, props?: Record<string, unknown>): void;
383
- /** Automatic pageview goals for the current URL. */
437
+ /**
438
+ * An event, any name (`track('signup')`, `track('Video Played', { id })`): one row that reaches the
439
+ * analytics property and converts the experiments whose goal it is (the goal keyed by its slug).
440
+ * Without a property it goes out as a goal row.
441
+ */
442
+ track(name: string, props?: Record<string, unknown>): void;
443
+ /**
444
+ * A page view: a `page` event for the analytics property, which also converts the pageview goals
445
+ * of the URL. Without a property, the goal rows of the URL go out instead.
446
+ */
384
447
  pageview(path?: string): void;
448
+ /**
449
+ * Ties this visitor to your user id (1..128 characters) with optional flat traits
450
+ * (`{ plan: 'pro' }`). Remembered in the browser and re-sent once per session; `null` forgets it.
451
+ */
452
+ identify(uid: string | null, traits?: Record<string, unknown>): void;
385
453
  /** Bind click goals (`type: 'click'`, CSS selector) to the document. Returns an unbind function. No-op outside the browser. */
386
454
  autoGoals(root?: Document | HTMLElement): () => void;
387
455
  flush(): Promise<void>;
@@ -403,4 +471,4 @@ declare function debugLog(kind: DebugKind, message: string, data?: Record<string
403
471
  /** Subscribe to debug entries (the devtools panel). Returns an unsubscribe function. */
404
472
  declare function onDebug(listener: (e: DebugEntry) => void): () => void;
405
473
 
406
- export { type AssignOptions, Assignment, CLOUD_ENDPOINT, type ClientOptions, ConfigError, type DebugEntry, type DebugKind, EMPTY_OVERRIDES, EventBatch, EventQueue, type EventQueueOptions, Experiment, type ExperimentOverride, ExperimentStatus, Factor, Flow, type FlowOutcome, Goal, HOLDOUT_KEY, Holdout, KEYED_FIELDS, LAYER_BUCKETS, MVT_MAX_COMBINATIONS, MVT_MAX_FACTORS, MVT_MAX_LEVELS, REMOTE_TTL_MS, REMOTE_WAIT_MS, type RedirectDecision, type RemoteOverrides, SDK_VERSION, type SplitHubClient, SplitHubConfig, SplitHubConfigInput, SplitHubEvent, TARGET_FIELDS, TARGET_OPS, TargetCondition, TargetField, TargetOp, TargetingContext, type Transport, type TransportOptions, Variant, applyRemoteOverrides, assign, browserContext, contextValue, controlVariant, countsForHoldout, createClient, createFetchTransport, debugLog, debugMode, decideRedirect, defineConfig, devNote, evaluateCondition, explainAssignment, fetchRemoteOverrides, getExperiment, getOrCreateSessionId, getOrCreateVisitorId, hasVisitorId, hashToUnit, holdoutExperiment, holdoutGroup, inLayer, inSchedule, isActive, isBot, isBrowser, isCrawler, isDebug, isDevDraft, isDevEnvironment, isRemoteOverrides, isSplitHubConfig, layerBucket, matchConditions, matchPath, measuredGoals, murmur3, mvtVariants, newId, newSessionId, newVisitorId, normalizePath, onDebug, parseCookies, parseForceParam, parseUserAgent, pickVariant, readRemoteCache, redirectTarget, resetDevNotes, resolveOverridesUrl, runFlow, validateFlow, writeRemoteCache };
474
+ export { type AssignOptions, Assignment, CLOUD_ENDPOINT, type ClientOptions, ConfigError, type DebugEntry, type DebugKind, EMPTY_OVERRIDES, EVENT_NAME_PATTERN, EventBatch, EventQueue, type EventQueueOptions, Experiment, type ExperimentOverride, ExperimentStatus, Factor, Flow, type FlowOutcome, Goal, HOLDOUT_KEY, Holdout, KEYED_FIELDS, LAYER_BUCKETS, MVT_MAX_COMBINATIONS, MVT_MAX_FACTORS, MVT_MAX_LEVELS, PROPERTY_KEY_PATTERN, Property, PropertyInput, PropertyStatus, REMOTE_TTL_MS, REMOTE_WAIT_MS, type RedirectDecision, type RemoteOverrides, SDK_VERSION, type SplitHubClient, SplitHubConfig, SplitHubConfigInput, SplitHubEvent, TARGET_FIELDS, TARGET_OPS, TargetCondition, TargetField, TargetOp, TargetingContext, type Transport, type TransportOptions, Variant, applyRemoteOverrides, assign, browserContext, contextValue, controlVariant, countsForHoldout, createClient, createFetchTransport, debugLog, debugMode, decideRedirect, defineConfig, devNote, evaluateCondition, eventKey, explainAssignment, fetchRemoteOverrides, getExperiment, getOrCreateSessionId, getOrCreateVisitorId, goalKeyFor, hasVisitorId, hashToUnit, holdoutExperiment, holdoutGroup, inLayer, inSchedule, isActive, isBot, isBrowser, isCrawler, isDebug, isDevDraft, isDevEnvironment, isRemoteOverrides, isSplitHubConfig, layerBucket, matchConditions, matchPath, measuredGoals, murmur3, mvtVariants, newId, newPropertyId, newSessionId, newVisitorId, normalizePath, normalizeProperty, onDebug, parseCookies, parseForceParam, parseUserAgent, pickProperty, pickVariant, readRemoteCache, redirectTarget, referrerOrigin, resetAnalyticsClaims, resetDevNotes, resolveOverridesUrl, runFlow, validateFlow, writeRemoteCache };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { S as SplitHubConfigInput, a as SplitHubConfig, E as Experiment, V as Variant, F as Factor, T as TargetingContext, A as Assignment, b as Flow, c as TargetCondition, d as TargetField, e as TargetOp, f as EventBatch, g as SplitHubEvent, h as ExperimentStatus, G as Goal, H as Holdout } from './types-DlycK6Py.js';
2
- export { n as ComponentExperimentInput, C as ComponentVariantInput, l as ExperimentBase, q as ExperimentInput, i as ExperimentKind, t as ExperimentMetrics, u as ExposureEvent, k as FlowNode, v as GoalEvent, r as GoalInput, m as GuardrailInput, M as MvtExperimentInput, p as RedirectExperimentInput, R as RedirectVariantInput, s as StorageInput, o as ValueExperimentInput, j as ValueVariantInput } from './types-DlycK6Py.js';
1
+ import { S as SplitHubConfigInput, a as SplitHubConfig, E as Experiment, V as Variant, F as Factor, P as PropertyInput, G as Goal, b as Property, T as TargetingContext, A as Assignment, c as Flow, d as TargetCondition, e as TargetField, f as TargetOp, g as EventBatch, h as SplitHubEvent, i as ExperimentStatus, j as PropertyStatus, H as Holdout } from './types-DKx9MXeC.js';
2
+ export { p as ComponentExperimentInput, C as ComponentVariantInput, D as EngageEvent, n as ExperimentBase, s as ExperimentInput, k as ExperimentKind, w as ExperimentMetrics, x as ExposureEvent, m as FlowNode, y as GoalEvent, u as GoalInput, t as GoalLabels, o as GuardrailInput, I as IdentifyEvent, M as MvtExperimentInput, z as PageEvent, r as RedirectExperimentInput, R as RedirectVariantInput, v as StorageInput, B as TrackEvent, q as ValueExperimentInput, l as ValueVariantInput } from './types-DKx9MXeC.js';
3
3
 
4
4
  declare class ConfigError extends Error {
5
5
  constructor(message: string);
@@ -20,6 +20,26 @@ declare function mvtVariants(expKey: string, factors: Record<string, Record<stri
20
20
  declare const HOLDOUT_KEY = "__holdout";
21
21
  /** Buckets per layer: an experiment's `layer.range` is a slice of 0..LAYER_BUCKETS. */
22
22
  declare const LAYER_BUCKETS = 100;
23
+ /** Analytics property ids, like every key: lowercase letters, digits, - and _. Generated ones look like `sh-x1h78w`. */
24
+ declare const PROPERTY_KEY_PATTERN: RegExp;
25
+ /** A new property id: `sh-` and six letters or digits without look-alikes (0/o, 1/l/i). */
26
+ declare function newPropertyId(): string;
27
+ /** Custom event names: letters, digits, spaces and `_ . : / -`, up to 64 characters (`signup`, `Video Played`). */
28
+ declare const EVENT_NAME_PATTERN: RegExp;
29
+ /**
30
+ * The goal key of an event name: `Video Played` → `video-played`, `signup` → `signup`.
31
+ * Lowercase, every run of other characters becomes `-`. Empty when nothing usable is left;
32
+ * check the result against `PROPERTY_KEY_PATTERN` before sending it as a key.
33
+ */
34
+ declare function eventKey(name: string): string;
35
+ /**
36
+ * The goal key an event name counts as: a declared goal key itself, the goal whose `event`
37
+ * is that name, or the name's slug (`eventKey`). Null when the name has no usable key.
38
+ */
39
+ declare function goalKeyFor(goals: ReadonlyArray<Pick<Goal, 'key' | 'event'>>, name: string): string | null;
40
+ declare function normalizeProperty(key: string, input: PropertyInput, goals: Goal[]): Property;
41
+ /** The property with this id, or null. Events only go to a property named explicitly, never to a guess. */
42
+ declare function pickProperty(config: Pick<SplitHubConfig, 'properties'>, key?: string | null): Property | null;
23
43
  /**
24
44
  * Validate and normalize a config. Call it once in `splithub.config.ts`:
25
45
  *
@@ -102,6 +122,9 @@ declare function resetDevNotes(): void;
102
122
  /** Explain an assignment that may surprise a developer: a draft, a paused test, a test outside its dates. */
103
123
  declare function explainAssignment(experiment: Experiment | undefined, a: Assignment): void;
104
124
 
125
+ /** Forget every claim (tests). */
126
+ declare function resetAnalyticsClaims(): void;
127
+
105
128
  /**
106
129
  * MurmurHash3 (32-bit, x86). Deterministic across browser, Node and edge
107
130
  * runtimes, with a uniform distribution suitable for bucketing.
@@ -182,6 +205,12 @@ declare function matchPath(pattern: string, pathname: string): boolean;
182
205
  * `?utm_source` survives) and the current hash kept unless `to` has one.
183
206
  */
184
207
  declare function redirectTarget(to: string, currentHref: string): URL;
208
+ /**
209
+ * Where a visit came from, as an exposure carries it: the referrer's origin only (never its path
210
+ * or query), `''` for a visit with no referrer (direct), and `undefined` when it says nothing
211
+ * about the source: a link from the same site, or a value that is not a URL.
212
+ */
213
+ declare function referrerOrigin(referrer: string | null | undefined, siteHost: string | null | undefined): string | undefined;
185
214
 
186
215
  interface RedirectDecision {
187
216
  experiment: string;
@@ -284,6 +313,12 @@ interface RemoteOverrides {
284
313
  added?: Experiment[];
285
314
  /** Goals declared in the dashboard (hosted config). */
286
315
  goals?: Goal[];
316
+ /** Analytics property status set from the dashboard or the CLI, by key. */
317
+ properties?: Record<string, {
318
+ status?: PropertyStatus;
319
+ }>;
320
+ /** Analytics properties created in the dashboard that are not in the config file. */
321
+ addedProperties?: Property[];
287
322
  /**
288
323
  * Holdout and layer seeds of the hosted config (sites on sh.js have no config file).
289
324
  * A config file's own `holdout` / `layers` win over these.
@@ -346,6 +381,11 @@ interface ClientOptions {
346
381
  ttlMs?: number;
347
382
  /** First visit (nothing cached): how long to wait for the overrides before deciding from the file. Default 400 ms; 0 decides at once. */
348
383
  waitMs?: number;
384
+ /**
385
+ * Overrides still on their way (the drop-in script stops waiting for experiments before they arrive).
386
+ * Analytics events for a property they may declare wait for them, up to 5 s.
387
+ */
388
+ arriving?: Promise<RemoteOverrides | null>;
349
389
  };
350
390
  /**
351
391
  * Visitor context for targeting (country, device, UTM ...). In the browser it
@@ -353,6 +393,21 @@ interface ClientOptions {
353
393
  * overrides JSON); on the server pass what you know from the request.
354
394
  */
355
395
  context?: TargetingContext;
396
+ /**
397
+ * Analytics property that receives pageviews and events: its id (`sh-x1h78w`), from
398
+ * `properties` in the config or from the dashboard. Without it no analytics events are sent.
399
+ */
400
+ property?: string | false;
401
+ /**
402
+ * Single-page apps: after the first pageview(), report every client-side navigation
403
+ * (history.pushState / replaceState / back) as a pageview too. Default true in the browser.
404
+ */
405
+ trackNavigation?: boolean;
406
+ /**
407
+ * Hash routers (`/#/pricing`): report the route after `#` as the page. Default: only when the
408
+ * path is `/` and the hash starts with `#/`; `false` never, `true` on any path.
409
+ */
410
+ trackHash?: boolean;
356
411
  onError?: (error: unknown) => void;
357
412
  }
358
413
  interface SplitHubClient {
@@ -379,9 +434,22 @@ interface SplitHubClient {
379
434
  value<T = unknown>(experimentKey: string): T;
380
435
  /** Record an exposure explicitly (the React components call this on mount). */
381
436
  exposure(experimentKey: string): void;
382
- track(goal: string, props?: Record<string, unknown>): void;
383
- /** Automatic pageview goals for the current URL. */
437
+ /**
438
+ * An event, any name (`track('signup')`, `track('Video Played', { id })`): one row that reaches the
439
+ * analytics property and converts the experiments whose goal it is (the goal keyed by its slug).
440
+ * Without a property it goes out as a goal row.
441
+ */
442
+ track(name: string, props?: Record<string, unknown>): void;
443
+ /**
444
+ * A page view: a `page` event for the analytics property, which also converts the pageview goals
445
+ * of the URL. Without a property, the goal rows of the URL go out instead.
446
+ */
384
447
  pageview(path?: string): void;
448
+ /**
449
+ * Ties this visitor to your user id (1..128 characters) with optional flat traits
450
+ * (`{ plan: 'pro' }`). Remembered in the browser and re-sent once per session; `null` forgets it.
451
+ */
452
+ identify(uid: string | null, traits?: Record<string, unknown>): void;
385
453
  /** Bind click goals (`type: 'click'`, CSS selector) to the document. Returns an unbind function. No-op outside the browser. */
386
454
  autoGoals(root?: Document | HTMLElement): () => void;
387
455
  flush(): Promise<void>;
@@ -403,4 +471,4 @@ declare function debugLog(kind: DebugKind, message: string, data?: Record<string
403
471
  /** Subscribe to debug entries (the devtools panel). Returns an unsubscribe function. */
404
472
  declare function onDebug(listener: (e: DebugEntry) => void): () => void;
405
473
 
406
- export { type AssignOptions, Assignment, CLOUD_ENDPOINT, type ClientOptions, ConfigError, type DebugEntry, type DebugKind, EMPTY_OVERRIDES, EventBatch, EventQueue, type EventQueueOptions, Experiment, type ExperimentOverride, ExperimentStatus, Factor, Flow, type FlowOutcome, Goal, HOLDOUT_KEY, Holdout, KEYED_FIELDS, LAYER_BUCKETS, MVT_MAX_COMBINATIONS, MVT_MAX_FACTORS, MVT_MAX_LEVELS, REMOTE_TTL_MS, REMOTE_WAIT_MS, type RedirectDecision, type RemoteOverrides, SDK_VERSION, type SplitHubClient, SplitHubConfig, SplitHubConfigInput, SplitHubEvent, TARGET_FIELDS, TARGET_OPS, TargetCondition, TargetField, TargetOp, TargetingContext, type Transport, type TransportOptions, Variant, applyRemoteOverrides, assign, browserContext, contextValue, controlVariant, countsForHoldout, createClient, createFetchTransport, debugLog, debugMode, decideRedirect, defineConfig, devNote, evaluateCondition, explainAssignment, fetchRemoteOverrides, getExperiment, getOrCreateSessionId, getOrCreateVisitorId, hasVisitorId, hashToUnit, holdoutExperiment, holdoutGroup, inLayer, inSchedule, isActive, isBot, isBrowser, isCrawler, isDebug, isDevDraft, isDevEnvironment, isRemoteOverrides, isSplitHubConfig, layerBucket, matchConditions, matchPath, measuredGoals, murmur3, mvtVariants, newId, newSessionId, newVisitorId, normalizePath, onDebug, parseCookies, parseForceParam, parseUserAgent, pickVariant, readRemoteCache, redirectTarget, resetDevNotes, resolveOverridesUrl, runFlow, validateFlow, writeRemoteCache };
474
+ export { type AssignOptions, Assignment, CLOUD_ENDPOINT, type ClientOptions, ConfigError, type DebugEntry, type DebugKind, EMPTY_OVERRIDES, EVENT_NAME_PATTERN, EventBatch, EventQueue, type EventQueueOptions, Experiment, type ExperimentOverride, ExperimentStatus, Factor, Flow, type FlowOutcome, Goal, HOLDOUT_KEY, Holdout, KEYED_FIELDS, LAYER_BUCKETS, MVT_MAX_COMBINATIONS, MVT_MAX_FACTORS, MVT_MAX_LEVELS, PROPERTY_KEY_PATTERN, Property, PropertyInput, PropertyStatus, REMOTE_TTL_MS, REMOTE_WAIT_MS, type RedirectDecision, type RemoteOverrides, SDK_VERSION, type SplitHubClient, SplitHubConfig, SplitHubConfigInput, SplitHubEvent, TARGET_FIELDS, TARGET_OPS, TargetCondition, TargetField, TargetOp, TargetingContext, type Transport, type TransportOptions, Variant, applyRemoteOverrides, assign, browserContext, contextValue, controlVariant, countsForHoldout, createClient, createFetchTransport, debugLog, debugMode, decideRedirect, defineConfig, devNote, evaluateCondition, eventKey, explainAssignment, fetchRemoteOverrides, getExperiment, getOrCreateSessionId, getOrCreateVisitorId, goalKeyFor, hasVisitorId, hashToUnit, holdoutExperiment, holdoutGroup, inLayer, inSchedule, isActive, isBot, isBrowser, isCrawler, isDebug, isDevDraft, isDevEnvironment, isRemoteOverrides, isSplitHubConfig, layerBucket, matchConditions, matchPath, measuredGoals, murmur3, mvtVariants, newId, newPropertyId, newSessionId, newVisitorId, normalizePath, normalizeProperty, onDebug, parseCookies, parseForceParam, parseUserAgent, pickProperty, pickVariant, readRemoteCache, redirectTarget, referrerOrigin, resetAnalyticsClaims, resetDevNotes, resolveOverridesUrl, runFlow, validateFlow, writeRemoteCache };
package/dist/index.js CHANGED
@@ -2,6 +2,7 @@ import {
2
2
  CLOUD_ENDPOINT,
3
3
  ConfigError,
4
4
  EMPTY_OVERRIDES,
5
+ EVENT_NAME_PATTERN,
5
6
  EventQueue,
6
7
  HOLDOUT_KEY,
7
8
  KEYED_FIELDS,
@@ -9,6 +10,7 @@ import {
9
10
  MVT_MAX_COMBINATIONS,
10
11
  MVT_MAX_FACTORS,
11
12
  MVT_MAX_LEVELS,
13
+ PROPERTY_KEY_PATTERN,
12
14
  REMOTE_TTL_MS,
13
15
  REMOTE_WAIT_MS,
14
16
  SDK_VERSION,
@@ -27,11 +29,13 @@ import {
27
29
  defineConfig,
28
30
  devNote,
29
31
  evaluateCondition,
32
+ eventKey,
30
33
  explainAssignment,
31
34
  fetchRemoteOverrides,
32
35
  getExperiment,
33
36
  getOrCreateSessionId,
34
37
  getOrCreateVisitorId,
38
+ goalKeyFor,
35
39
  hasVisitorId,
36
40
  hashToUnit,
37
41
  holdoutExperiment,
@@ -54,22 +58,27 @@ import {
54
58
  murmur3,
55
59
  mvtVariants,
56
60
  newId,
61
+ newPropertyId,
57
62
  newSessionId,
58
63
  newVisitorId,
59
64
  normalizePath,
65
+ normalizeProperty,
60
66
  onDebug,
61
67
  parseCookies,
62
68
  parseForceParam,
63
69
  parseUserAgent,
70
+ pickProperty,
64
71
  pickVariant,
65
72
  readRemoteCache,
66
73
  redirectTarget,
74
+ referrerOrigin,
75
+ resetAnalyticsClaims,
67
76
  resetDevNotes,
68
77
  resolveOverridesUrl,
69
78
  runFlow,
70
79
  validateFlow,
71
80
  writeRemoteCache
72
- } from "./chunk-D4LRWPNH.js";
81
+ } from "./chunk-7CE2FI5Y.js";
73
82
 
74
83
  // src/redirect.ts
75
84
  function decideRedirect(config, pathname, visitorId, context = {}, overrides = {}, explain) {
@@ -92,6 +101,7 @@ export {
92
101
  CLOUD_ENDPOINT,
93
102
  ConfigError,
94
103
  EMPTY_OVERRIDES,
104
+ EVENT_NAME_PATTERN,
95
105
  EventQueue,
96
106
  HOLDOUT_KEY,
97
107
  KEYED_FIELDS,
@@ -99,6 +109,7 @@ export {
99
109
  MVT_MAX_COMBINATIONS,
100
110
  MVT_MAX_FACTORS,
101
111
  MVT_MAX_LEVELS,
112
+ PROPERTY_KEY_PATTERN,
102
113
  REMOTE_TTL_MS,
103
114
  REMOTE_WAIT_MS,
104
115
  SDK_VERSION,
@@ -118,11 +129,13 @@ export {
118
129
  defineConfig,
119
130
  devNote,
120
131
  evaluateCondition,
132
+ eventKey,
121
133
  explainAssignment,
122
134
  fetchRemoteOverrides,
123
135
  getExperiment,
124
136
  getOrCreateSessionId,
125
137
  getOrCreateVisitorId,
138
+ goalKeyFor,
126
139
  hasVisitorId,
127
140
  hashToUnit,
128
141
  holdoutExperiment,
@@ -145,16 +158,21 @@ export {
145
158
  murmur3,
146
159
  mvtVariants,
147
160
  newId,
161
+ newPropertyId,
148
162
  newSessionId,
149
163
  newVisitorId,
150
164
  normalizePath,
165
+ normalizeProperty,
151
166
  onDebug,
152
167
  parseCookies,
153
168
  parseForceParam,
154
169
  parseUserAgent,
170
+ pickProperty,
155
171
  pickVariant,
156
172
  readRemoteCache,
157
173
  redirectTarget,
174
+ referrerOrigin,
175
+ resetAnalyticsClaims,
158
176
  resetDevNotes,
159
177
  resolveOverridesUrl,
160
178
  runFlow,
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/redirect.ts"],"sourcesContent":["import { assign, isActive } from './assignment';\nimport { normalizePath, matchPath } from './paths';\nimport type { Assignment, Experiment, SplitHubConfig, TargetingContext } from './types';\n\nexport interface RedirectDecision {\n experiment: string;\n variant: string;\n /** Destination (`to` of the variant) when the visitor must be moved; null when they stay. */\n to: string | null;\n /** Why this variant: `assigned`, `dev` (a draft in development) or `override` (`?sh_force`). */\n reason: Assignment['reason'];\n}\n\n/**\n * Which redirect experiment applies to `pathname`, and where the visitor goes.\n * The first active experiment that matches and assigns a variant wins. Pure:\n * sh.js and the Next.js middleware ask the same question and get the same answer.\n * `explain` hears every assignment it made for a matching experiment (the\n * middleware prints the surprising ones in development).\n */\nexport function decideRedirect(\n config: SplitHubConfig,\n pathname: string,\n visitorId: string,\n context: TargetingContext = {},\n overrides: Record<string, string> = {},\n explain?: (experiment: Experiment, assignment: Assignment) => void\n): RedirectDecision | null {\n for (const exp of config.experiments) {\n if (exp.kind !== 'redirect' || !exp.match || !matchPath(exp.match, pathname)) continue;\n if (!isActive(config, exp, context.now)) {\n explain?.(exp, { experiment: exp.key, variant: null, reason: 'not_running' });\n continue;\n }\n const a = assign(config, exp.key, visitorId, { overrides, context });\n explain?.(exp, a);\n if (!a.variant) continue;\n const to = a.variant.to || null;\n const stays = !to || normalizePath(to.split(/[?#]/)[0] ?? '') === normalizePath(pathname);\n return { experiment: exp.key, variant: a.variant.key, to: stays ? null : to, reason: a.reason };\n }\n return null;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoBO,SAAS,eACd,QACA,UACA,WACA,UAA4B,CAAC,GAC7B,YAAoC,CAAC,GACrC,SACyB;AACzB,aAAW,OAAO,OAAO,aAAa;AACpC,QAAI,IAAI,SAAS,cAAc,CAAC,IAAI,SAAS,CAAC,UAAU,IAAI,OAAO,QAAQ,EAAG;AAC9E,QAAI,CAAC,SAAS,QAAQ,KAAK,QAAQ,GAAG,GAAG;AACvC,gBAAU,KAAK,EAAE,YAAY,IAAI,KAAK,SAAS,MAAM,QAAQ,cAAc,CAAC;AAC5E;AAAA,IACF;AACA,UAAM,IAAI,OAAO,QAAQ,IAAI,KAAK,WAAW,EAAE,WAAW,QAAQ,CAAC;AACnE,cAAU,KAAK,CAAC;AAChB,QAAI,CAAC,EAAE,QAAS;AAChB,UAAM,KAAK,EAAE,QAAQ,MAAM;AAC3B,UAAM,QAAQ,CAAC,MAAM,cAAc,GAAG,MAAM,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,cAAc,QAAQ;AACxF,WAAO,EAAE,YAAY,IAAI,KAAK,SAAS,EAAE,QAAQ,KAAK,IAAI,QAAQ,OAAO,IAAI,QAAQ,EAAE,OAAO;AAAA,EAChG;AACA,SAAO;AACT;","names":[]}
1
+ {"version":3,"sources":["../src/redirect.ts"],"sourcesContent":["import { assign, isActive } from './assignment';\nimport { normalizePath, matchPath } from './paths';\nimport type { Assignment, Experiment, SplitHubConfig, TargetingContext } from './types';\n\nexport interface RedirectDecision {\n experiment: string;\n variant: string;\n /** Destination (`to` of the variant) when the visitor must be moved; null when they stay. */\n to: string | null;\n /** Why this variant: `assigned`, `dev` (a draft in development) or `override` (`?sh_force`). */\n reason: Assignment['reason'];\n}\n\n/**\n * Which redirect experiment applies to `pathname`, and where the visitor goes.\n * The first active experiment that matches and assigns a variant wins. Pure:\n * sh.js and the Next.js middleware ask the same question and get the same answer.\n * `explain` hears every assignment it made for a matching experiment (the\n * middleware prints the surprising ones in development).\n */\nexport function decideRedirect(\n config: SplitHubConfig,\n pathname: string,\n visitorId: string,\n context: TargetingContext = {},\n overrides: Record<string, string> = {},\n explain?: (experiment: Experiment, assignment: Assignment) => void\n): RedirectDecision | null {\n for (const exp of config.experiments) {\n if (exp.kind !== 'redirect' || !exp.match || !matchPath(exp.match, pathname)) continue;\n if (!isActive(config, exp, context.now)) {\n explain?.(exp, { experiment: exp.key, variant: null, reason: 'not_running' });\n continue;\n }\n const a = assign(config, exp.key, visitorId, { overrides, context });\n explain?.(exp, a);\n if (!a.variant) continue;\n const to = a.variant.to || null;\n const stays = !to || normalizePath(to.split(/[?#]/)[0] ?? '') === normalizePath(pathname);\n return { experiment: exp.key, variant: a.variant.key, to: stays ? null : to, reason: a.reason };\n }\n return null;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoBO,SAAS,eACd,QACA,UACA,WACA,UAA4B,CAAC,GAC7B,YAAoC,CAAC,GACrC,SACyB;AACzB,aAAW,OAAO,OAAO,aAAa;AACpC,QAAI,IAAI,SAAS,cAAc,CAAC,IAAI,SAAS,CAAC,UAAU,IAAI,OAAO,QAAQ,EAAG;AAC9E,QAAI,CAAC,SAAS,QAAQ,KAAK,QAAQ,GAAG,GAAG;AACvC,gBAAU,KAAK,EAAE,YAAY,IAAI,KAAK,SAAS,MAAM,QAAQ,cAAc,CAAC;AAC5E;AAAA,IACF;AACA,UAAM,IAAI,OAAO,QAAQ,IAAI,KAAK,WAAW,EAAE,WAAW,QAAQ,CAAC;AACnE,cAAU,KAAK,CAAC;AAChB,QAAI,CAAC,EAAE,QAAS;AAChB,UAAM,KAAK,EAAE,QAAQ,MAAM;AAC3B,UAAM,QAAQ,CAAC,MAAM,cAAc,GAAG,MAAM,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,cAAc,QAAQ;AACxF,WAAO,EAAE,YAAY,IAAI,KAAK,SAAS,EAAE,QAAQ,KAAK,IAAI,QAAQ,OAAO,IAAI,QAAQ,EAAE,OAAO;AAAA,EAChG;AACA,SAAO;AACT;","names":[]}
@@ -92,7 +92,10 @@ interface ExperimentBase {
92
92
  startAt?: string;
93
93
  endAt?: string;
94
94
  };
95
- /** Goal key from `goals`. Used as the primary metric for the verdict. */
95
+ /**
96
+ * The goal the verdict is judged on: a key from `goals` or any event name (`'signup'`,
97
+ * `'Video Played'`). A name not declared in `goals` becomes an event goal keyed by its slug.
98
+ */
96
99
  goal?: string;
97
100
  /** Hash seed. Change it to reshuffle every visitor. Defaults to the experiment key. */
98
101
  seed?: string;
@@ -114,7 +117,7 @@ interface ExperimentBase {
114
117
  */
115
118
  goodSample?: number;
116
119
  /**
117
- * Goals read beside the primary `goal`. `secondary`: informational, compared the same way.
120
+ * Goals (keys or event names) read beside the primary `goal`. `secondary`: informational, compared the same way.
118
121
  * `guardrails`: must not get significantly worse; a variant that hurts one is never called the winner.
119
122
  * A guardrail is worse when its conversion rate drops; pass `{ goal, worse: 'higher' }` for goals
120
123
  * where more is bad (refunds, errors).
@@ -165,21 +168,28 @@ interface MvtExperimentInput extends ExperimentBase {
165
168
  factors: Record<string, Record<string, unknown>>;
166
169
  }
167
170
  type ExperimentInput = ComponentExperimentInput | ValueExperimentInput | RedirectExperimentInput | MvtExperimentInput;
168
- type GoalInput = {
171
+ /** Shared by every goal: a label for people, and a fixed value per conversion for analytics. */
172
+ interface GoalLabels {
173
+ /** Human name ("Sign up"); the key stays what the code sends. */
174
+ name?: string;
175
+ description?: string;
176
+ /** Value of one conversion in analytics reports when the event carries no `revenue` prop. */
177
+ value?: number;
178
+ }
179
+ type GoalInput = (GoalLabels & {
169
180
  type: 'event';
170
181
  revenue?: boolean;
171
- description?: string;
172
- } | {
182
+ /** The event name analytics matches when it differs from the key (`'Video Played'` for key `video-played`). */
183
+ event?: string;
184
+ }) | (GoalLabels & {
173
185
  type: 'pageview';
174
186
  path: string;
175
- description?: string;
176
- }
187
+ })
177
188
  /** Counted when a visitor clicks an element matching the CSS selector (auto-tracked by the SDK and the drop-in script). */
178
- | {
189
+ | (GoalLabels & {
179
190
  type: 'click';
180
191
  selector: string;
181
- description?: string;
182
- };
192
+ });
183
193
  type StorageInput = {
184
194
  mode: 'cloud';
185
195
  /** Public project key (`pk_...`). Safe to ship to the browser. */
@@ -191,11 +201,29 @@ type StorageInput = {
191
201
  /** URL of your own ingest route, e.g. `/api/splithub`. */
192
202
  endpoint: string;
193
203
  };
204
+ /**
205
+ * An analytics property: a stream of pageviews and custom events, read as reports
206
+ * (visitors, pages, sources, events, goal conversions). Declared like experiments;
207
+ * `paused` drops its events at ingest.
208
+ */
209
+ interface PropertyInput {
210
+ /** Default `running`. */
211
+ status?: PropertyStatus;
212
+ /** Human name shown in the dashboard and CLI (up to 80 characters). */
213
+ name?: string;
214
+ description?: string;
215
+ /** Goal keys from `goals` reported as conversions of this property. Default: every goal of the project. */
216
+ goals?: string[];
217
+ }
218
+ type PropertyStatus = 'running' | 'paused';
194
219
  interface SplitHubConfigInput {
195
220
  project: string;
196
221
  storage: StorageInput;
222
+ /** Goals by key: events you mark as goals, page visits or clicks. */
197
223
  goals?: Record<string, GoalInput>;
198
224
  experiments: Record<string, ExperimentInput>;
225
+ /** Analytics properties by key: pageviews and custom events, no variants. */
226
+ properties?: Record<string, PropertyInput>;
199
227
  /** Cookie / localStorage key for the visitor id. Defaults to `sh_vid`. */
200
228
  visitorKey?: string;
201
229
  /**
@@ -212,7 +240,7 @@ interface SplitHubConfigInput {
212
240
  * Holdout: this share of visitors (`percent`, 0..50) sees the control in every experiment and
213
241
  * is compared with everyone else as the reserved experiment `__holdout` (variants `holdout`,
214
242
  * `enrolled`) for the long-term effect of all your tests together. `goal` is its primary goal
215
- * (default: the first declared goal); the other goals are read as secondary metrics.
243
+ * (any event name; default: the first declared goal); the other goals are read as secondary metrics.
216
244
  */
217
245
  holdout?: {
218
246
  percent: number;
@@ -294,6 +322,23 @@ interface Goal {
294
322
  selector?: string | null;
295
323
  revenue: boolean;
296
324
  description: string | null;
325
+ /** Human name; absent = show the key. */
326
+ name?: string;
327
+ /** Fixed value of one conversion in analytics; absent = none. */
328
+ value?: number;
329
+ /** Event name analytics matches instead of the key. */
330
+ event?: string;
331
+ }
332
+ interface Property {
333
+ key: string;
334
+ status: PropertyStatus;
335
+ /** Human name; absent = show the key. */
336
+ name?: string;
337
+ description: string | null;
338
+ /** Goal keys reported as conversions; empty = every goal of the project. */
339
+ goals: string[];
340
+ /** Where the property was defined: the config file (default) or the cloud dashboard. */
341
+ origin?: 'config' | 'dashboard';
297
342
  }
298
343
  interface SplitHubConfig {
299
344
  project: string;
@@ -302,6 +347,8 @@ interface SplitHubConfig {
302
347
  runDraftsInDev: boolean;
303
348
  goals: Goal[];
304
349
  experiments: Experiment[];
350
+ /** Analytics properties; absent = none. */
351
+ properties?: Property[];
305
352
  /** Layer seeds by key; a layer missing here uses its key as the seed. */
306
353
  layers?: Record<string, {
307
354
  seed: string;
@@ -320,6 +367,11 @@ interface ExposureEvent {
320
367
  /** Unix ms. */
321
368
  ts: number;
322
369
  url?: string;
370
+ /**
371
+ * Where the visit came from: the referrer's origin (no path, no query), `''` for a direct
372
+ * visit; absent when unknown. The cloud derives the visitor's channel and source from it.
373
+ */
374
+ ref?: string;
323
375
  }
324
376
  interface GoalEvent {
325
377
  id: string;
@@ -331,7 +383,57 @@ interface GoalEvent {
331
383
  url?: string;
332
384
  props?: Record<string, unknown>;
333
385
  }
334
- type SplitHubEvent = ExposureEvent | GoalEvent;
386
+ /** A page view of an analytics property. `ref` is the document referrer, `title` the page title. */
387
+ interface PageEvent {
388
+ id: string;
389
+ type: 'page';
390
+ prop: string;
391
+ vid: string;
392
+ sid: string;
393
+ ts: number;
394
+ url: string;
395
+ title?: string;
396
+ ref?: string;
397
+ }
398
+ /** A custom event of an analytics property (`signup`, `Video Played`), with optional props. */
399
+ interface TrackEvent {
400
+ id: string;
401
+ type: 'event';
402
+ prop: string;
403
+ name: string;
404
+ vid: string;
405
+ sid: string;
406
+ ts: number;
407
+ url?: string;
408
+ props?: Record<string, unknown>;
409
+ }
410
+ /**
411
+ * Time on page and scroll depth for the page just left, sent on route change and page hide.
412
+ * `ms`: visible time on that page (0..3,600,000); `scroll`: deepest scroll, percent (0..100). Not billed.
413
+ */
414
+ interface EngageEvent {
415
+ id: string;
416
+ type: 'engage';
417
+ prop: string;
418
+ vid: string;
419
+ sid: string;
420
+ ts: number;
421
+ url: string;
422
+ ms: number;
423
+ scroll: number;
424
+ }
425
+ /** Ties the anonymous visitor to the app's user id (1..128 characters), with flat traits up to 4 KB. Not billed. */
426
+ interface IdentifyEvent {
427
+ id: string;
428
+ type: 'identify';
429
+ prop: string;
430
+ vid: string;
431
+ sid: string;
432
+ ts: number;
433
+ uid: string;
434
+ traits?: Record<string, string | number | boolean>;
435
+ }
436
+ type SplitHubEvent = ExposureEvent | GoalEvent | PageEvent | TrackEvent | EngageEvent | IdentifyEvent;
335
437
  interface EventBatch {
336
438
  project: string;
337
439
  sdk: string;
@@ -349,4 +451,4 @@ interface Assignment {
349
451
  reason: 'assigned' | 'dev' | 'not_running' | 'outside_traffic' | 'unknown_experiment' | 'override' | 'targeting' | 'bot' | 'no_visitor' | 'layer' | 'holdout' | 'pending';
350
452
  }
351
453
 
352
- export type { Assignment as A, ComponentVariantInput as C, Experiment as E, Factor as F, Goal as G, Holdout as H, MvtExperimentInput as M, RedirectVariantInput as R, SplitHubConfigInput as S, TargetingContext as T, Variant as V, SplitHubConfig as a, Flow as b, TargetCondition as c, TargetField as d, TargetOp as e, EventBatch as f, SplitHubEvent as g, ExperimentStatus as h, ExperimentKind as i, ValueVariantInput as j, FlowNode as k, ExperimentBase as l, GuardrailInput as m, ComponentExperimentInput as n, ValueExperimentInput as o, RedirectExperimentInput as p, ExperimentInput as q, GoalInput as r, StorageInput as s, ExperimentMetrics as t, ExposureEvent as u, GoalEvent as v };
454
+ export type { Assignment as A, TrackEvent as B, ComponentVariantInput as C, EngageEvent as D, Experiment as E, Factor as F, Goal as G, Holdout as H, IdentifyEvent as I, MvtExperimentInput as M, PropertyInput as P, RedirectVariantInput as R, SplitHubConfigInput as S, TargetingContext as T, Variant as V, SplitHubConfig as a, Property as b, Flow as c, TargetCondition as d, TargetField as e, TargetOp as f, EventBatch as g, SplitHubEvent as h, ExperimentStatus as i, PropertyStatus as j, ExperimentKind as k, ValueVariantInput as l, FlowNode as m, ExperimentBase as n, GuardrailInput as o, ComponentExperimentInput as p, ValueExperimentInput as q, RedirectExperimentInput as r, ExperimentInput as s, GoalLabels as t, GoalInput as u, StorageInput as v, ExperimentMetrics as w, ExposureEvent as x, GoalEvent as y, PageEvent as z };