@splithub/core 0.4.3 → 0.5.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.cts CHANGED
@@ -1,5 +1,5 @@
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';
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 AppInfo, d as Flow, e as TargetCondition, f as TargetField, g as TargetOp, h as EventBatch, i as SplitHubEvent, j as ExperimentStatus, k as PropertyStatus, H as Holdout } from './types-0c_5qhVX.cjs';
2
+ export { o as AppPlatform, r as ComponentExperimentInput, C as ComponentVariantInput, K as EngageEvent, p as ExperimentBase, u as ExperimentInput, l as ExperimentKind, z as ExperimentMetrics, B as ExposureEvent, n as FlowNode, D as GoalEvent, w as GoalInput, v as GoalLabels, q as GuardrailInput, L as IdentifyEvent, M as MvtExperimentInput, I as PageEvent, y as PropertyKind, t as RedirectExperimentInput, R as RedirectVariantInput, x as StorageInput, J as TrackEvent, s as ValueExperimentInput, m as ValueVariantInput } from './types-0c_5qhVX.cjs';
3
3
 
4
4
  declare class ConfigError extends Error {
5
5
  constructor(message: string);
@@ -138,7 +138,41 @@ declare function newId(prefix?: string): string;
138
138
  declare function newVisitorId(): string;
139
139
  declare function newSessionId(): string;
140
140
 
141
+ /**
142
+ * Synchronous key-value storage, so assignment stays synchronous. React Native preloads
143
+ * AsyncStorage into memory or uses MMKV; native SDKs use UserDefaults / SharedPreferences.
144
+ */
145
+ interface KeyValueStorage {
146
+ getItem(key: string): string | null;
147
+ setItem(key: string, value: string): void;
148
+ removeItem(key: string): void;
149
+ }
150
+ /**
151
+ * What an app gives the client instead of a browser page. With it the client is a persistent
152
+ * client: no cookies, no `location` / `history` / `document`, no sendBeacon, and pageviews come
153
+ * only from `screen()` calls.
154
+ */
155
+ interface PlatformAdapter {
156
+ /** Persistent: visitor id, user id, the overrides cache and the offline queue. */
157
+ storage: KeyValueStorage;
158
+ /** Per launch: session id, exposures already sent. Defaults to an in-memory map. */
159
+ session?: KeyValueStorage;
160
+ /** Attached to every batch. */
161
+ app?: AppInfo;
162
+ /** Platform, appVersion, language, timezone, device, os. `platform` / `appVersion` default to `app`'s. */
163
+ context?: TargetingContext;
164
+ /** The app went to the background: the client flushes the queue and closes the screen's engagement. Returns an unsubscribe function. */
165
+ onBackground?(cb: () => void): () => void;
166
+ /** The app came back: after 30 minutes away a new session starts. Returns an unsubscribe function. */
167
+ onForeground?(cb: () => void): () => void;
168
+ }
169
+ /** A storage that lives as long as the process: the default `session` of an adapter, and handy in tests. */
170
+ declare function memoryStorage(initial?: Record<string, string>): KeyValueStorage;
171
+
172
+ /** A web page. React Native has a `window` but no page (and `navigator.product` says so). */
141
173
  declare const isBrowser: () => boolean;
174
+ /** React Native (Hermes or JSC): a `window` and a `navigator`, but no page. */
175
+ declare const isReactNative: () => boolean;
142
176
  /**
143
177
  * Visitor id lookup order: cookie → localStorage → new. The value is written
144
178
  * to both so that SSR (cookie) and SPA (localStorage) agree.
@@ -154,6 +188,12 @@ declare const TARGET_OPS: TargetOp[];
154
188
  declare const KEYED_FIELDS: TargetField[];
155
189
  /** Value of a context field as a lowercase string, or undefined when unknown. */
156
190
  declare function contextValue(field: TargetField, key: string | undefined, ctx: TargetingContext): string | undefined;
191
+ /**
192
+ * Orders two versions: dotted parts compare as numbers when both are digits
193
+ * (`2.10.0` > `2.9`), otherwise as strings; a missing part counts as 0, so
194
+ * `2.0` equals `2`. Plain numbers are one-part versions. Native SDKs port this as is.
195
+ */
196
+ declare function compareVersions(a: string, b: string): number;
157
197
  declare function evaluateCondition(c: TargetCondition, ctx: TargetingContext): boolean;
158
198
  declare function matchConditions(conditions: TargetCondition[], match: 'all' | 'any', ctx: TargetingContext): boolean;
159
199
  type FlowOutcome = {
@@ -244,6 +284,8 @@ interface TransportOptions {
244
284
  * `fetch(..., { keepalive: true })` on page hide, which also outlives the page.
245
285
  */
246
286
  keyInQuery?: boolean;
287
+ /** `fetch(..., { keepalive })`; default true. Apps pass false: there is no page to outlive. */
288
+ keepalive?: boolean;
247
289
  }
248
290
  /** Default transport: fetch with keepalive; sendBeacon on page hide when the endpoint allows it. */
249
291
  declare function createFetchTransport(options: TransportOptions): Transport;
@@ -255,12 +297,24 @@ interface EventQueueOptions {
255
297
  maxBatch?: number;
256
298
  /** Flush at least this often (ms). Default 2000. */
257
299
  flushInterval?: number;
258
- /** Events kept while the endpoint is unreachable; the oldest go first. Default 200. */
300
+ /** Events kept while the endpoint is unreachable; the oldest go first. Default 200, 1000 with `storage`. */
259
301
  maxQueue?: number;
260
- /** Attempts per event before it is dropped. Default 5. */
302
+ /**
303
+ * Attempts per event before it is dropped. Default 5. With `storage`, network failures and
304
+ * 5xx / 408 never use up attempts; a 429 always does (the project is throttled, over quota or gone).
305
+ */
261
306
  maxAttempts?: number;
307
+ /**
308
+ * Apps: unsent events are kept here (key `sh_queue`), so they survive a restart and an offline
309
+ * stretch; network failures and 5xx / 408 back off up to 60 s. Queues sharing one storage share
310
+ * `sh_queue`: only the first restores it, and each write carries every live queue's events.
311
+ */
312
+ storage?: KeyValueStorage;
313
+ /** Sent with every batch (apps). */
314
+ app?: AppInfo;
262
315
  onError?: (error: unknown) => void;
263
316
  }
317
+ declare const QUEUE_STORAGE_KEY = "sh_queue";
264
318
  /**
265
319
  * Batches events and sends them on a timer, when a batch is full, and when the page is
266
320
  * hidden (sendBeacon / keepalive). A failed batch is retried with exponential backoff and
@@ -272,7 +326,12 @@ declare class EventQueue {
272
326
  private readonly options;
273
327
  private pending;
274
328
  private retry;
329
+ /** Batches on their way: still persisted until the transport says they arrived. */
330
+ private readonly inflight;
275
331
  private attempts;
332
+ /** 429s in a row: they drop the batch after `maxAttempts`, storage or not. */
333
+ private throttled;
334
+ private destroyed;
276
335
  private timer;
277
336
  private backoffUntil;
278
337
  private readonly maxBatch;
@@ -281,6 +340,9 @@ declare class EventQueue {
281
340
  private readonly maxAttempts;
282
341
  private unbind;
283
342
  constructor(options: EventQueueOptions);
343
+ /** Hands over the events waiting here (not those on their way) to a queue that adopts them. */
344
+ private release;
345
+ private persist;
284
346
  private bind;
285
347
  private schedule;
286
348
  push(event: SplitHubEvent): void;
@@ -334,27 +396,44 @@ declare const EMPTY_OVERRIDES: RemoteOverrides;
334
396
  /** Pure merge: returns a new config, never mutates the input. */
335
397
  declare function applyRemoteOverrides(config: SplitHubConfig, overrides: RemoteOverrides | null | undefined): SplitHubConfig;
336
398
  declare function isRemoteOverrides(value: unknown): value is RemoteOverrides;
337
- /** `https://go.splithub.io/v1/events` → `https://go.splithub.io/v1/overrides/<pk>.json` */
338
- declare function resolveOverridesUrl(eventsEndpoint: string, publicKey: string): string;
399
+ /**
400
+ * `https://go.splithub.io/v1/events` → `https://go.splithub.io/v1/overrides/<pk>.json`.
401
+ * `all` (apps: clients with a platform adapter) also asks for every experiment pushed from
402
+ * `splithub.config.ts`: an app has no config file to learn them from. Websites never ask for it.
403
+ */
404
+ declare function resolveOverridesUrl(eventsEndpoint: string, publicKey: string, all?: boolean): string;
339
405
  interface CacheEntry {
340
406
  fetchedAt: number;
341
407
  overrides: RemoteOverrides;
342
408
  }
343
409
  declare const REMOTE_TTL_MS = 60000;
344
- declare function readRemoteCache(publicKey: string): CacheEntry | null;
345
- declare function writeRemoteCache(publicKey: string, overrides: RemoteOverrides): void;
410
+ declare function readRemoteCache(publicKey: string, store?: KeyValueStorage | null, all?: boolean): CacheEntry | null;
411
+ declare function writeRemoteCache(publicKey: string, overrides: RemoteOverrides, store?: KeyValueStorage | null, all?: boolean): void;
346
412
  declare function fetchRemoteOverrides(url: string, fetchImpl?: typeof fetch): Promise<RemoteOverrides | null>;
347
413
 
348
414
  declare const SDK_VERSION = "0.1.0";
349
- /** First visit without cached overrides: the longest the client waits for them. The fetch usually takes ~150 ms. */
415
+ /**
416
+ * First visit (or first app launch) without cached overrides: the longest the client waits for
417
+ * them. The fetch usually takes ~150 ms. Apps wait the same: later launches read the cache.
418
+ */
350
419
  declare const REMOTE_WAIT_MS = 400;
351
420
  declare const CLOUD_ENDPOINT = "https://go.splithub.io/v1/events";
421
+ /** An app away this long starts a new session when it comes back. */
422
+ declare const SESSION_GAP_MS: number;
352
423
  interface ClientOptions {
353
424
  /** Provide on the server (from the cookie) so SSR and client agree. */
354
425
  visitorId?: string;
355
426
  sessionId?: string;
356
427
  /** Custom transport, e.g. a no-op for tests or SSR. */
357
428
  transport?: Transport;
429
+ /**
430
+ * Apps (React Native, desktop): storage, app info and lifecycle instead of a browser page.
431
+ * The client then keeps the visitor in `storage`, persists unsent events (`sh_queue`), sends
432
+ * no pageviews of its own (call `screen()`), and starts a new session after 30 minutes in the background.
433
+ */
434
+ platform?: PlatformAdapter;
435
+ /** `sdk` of every batch. Default `core/<version>`; wrappers name themselves (`react-native/1.0.0`). */
436
+ sdk?: string;
358
437
  /**
359
438
  * Send the cloud key as `?key=` so page-hide batches can use `navigator.sendBeacon`.
360
439
  * On by default for SplitHub Cloud (the key is public); off for a custom endpoint,
@@ -413,6 +492,7 @@ interface ClientOptions {
413
492
  interface SplitHubClient {
414
493
  readonly config: SplitHubConfig;
415
494
  readonly visitorId: string;
495
+ /** May change during the client's life (an app back after 30 minutes away): read it each time, do not keep a copy. */
416
496
  readonly sessionId: string;
417
497
  /** Targeting context used for assignments. */
418
498
  readonly context: TargetingContext;
@@ -445,6 +525,12 @@ interface SplitHubClient {
445
525
  * of the URL. Without a property, the goal rows of the URL go out instead.
446
526
  */
447
527
  pageview(path?: string): void;
528
+ /**
529
+ * A screen of an app (or a virtual page on the web): a `page` event with url `/${name}` (or
530
+ * `name` itself when it starts with `/`) and the name as title. `props` are accepted for
531
+ * later; page rows carry none on the wire yet.
532
+ */
533
+ screen(name: string, props?: Record<string, unknown>): void;
448
534
  /**
449
535
  * Ties this visitor to your user id (1..128 characters) with optional flat traits
450
536
  * (`{ plan: 'pro' }`). Remembered in the browser and re-sent once per session; `null` forgets it.
@@ -454,6 +540,11 @@ interface SplitHubClient {
454
540
  autoGoals(root?: Document | HTMLElement): () => void;
455
541
  flush(): Promise<void>;
456
542
  destroy(): void;
543
+ /**
544
+ * Binds the app lifecycle (background / foreground) again after `destroy()`, as a provider does when
545
+ * StrictMode mounts it a second time. Idempotent; a no-op on the web, where the next event binds.
546
+ */
547
+ resume(): void;
457
548
  }
458
549
  declare function createClient(config: SplitHubConfig, options?: ClientOptions): SplitHubClient;
459
550
 
@@ -471,4 +562,4 @@ declare function debugLog(kind: DebugKind, message: string, data?: Record<string
471
562
  /** Subscribe to debug entries (the devtools panel). Returns an unsubscribe function. */
472
563
  declare function onDebug(listener: (e: DebugEntry) => void): () => void;
473
564
 
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 };
565
+ export { AppInfo, 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, type KeyValueStorage, LAYER_BUCKETS, MVT_MAX_COMBINATIONS, MVT_MAX_FACTORS, MVT_MAX_LEVELS, PROPERTY_KEY_PATTERN, type PlatformAdapter, Property, PropertyInput, PropertyStatus, QUEUE_STORAGE_KEY, REMOTE_TTL_MS, REMOTE_WAIT_MS, type RedirectDecision, type RemoteOverrides, SDK_VERSION, SESSION_GAP_MS, type SplitHubClient, SplitHubConfig, SplitHubConfigInput, SplitHubEvent, TARGET_FIELDS, TARGET_OPS, TargetCondition, TargetField, TargetOp, TargetingContext, type Transport, type TransportOptions, Variant, applyRemoteOverrides, assign, browserContext, compareVersions, 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, isReactNative, isRemoteOverrides, isSplitHubConfig, layerBucket, matchConditions, matchPath, measuredGoals, memoryStorage, 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, 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';
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 AppInfo, d as Flow, e as TargetCondition, f as TargetField, g as TargetOp, h as EventBatch, i as SplitHubEvent, j as ExperimentStatus, k as PropertyStatus, H as Holdout } from './types-0c_5qhVX.js';
2
+ export { o as AppPlatform, r as ComponentExperimentInput, C as ComponentVariantInput, K as EngageEvent, p as ExperimentBase, u as ExperimentInput, l as ExperimentKind, z as ExperimentMetrics, B as ExposureEvent, n as FlowNode, D as GoalEvent, w as GoalInput, v as GoalLabels, q as GuardrailInput, L as IdentifyEvent, M as MvtExperimentInput, I as PageEvent, y as PropertyKind, t as RedirectExperimentInput, R as RedirectVariantInput, x as StorageInput, J as TrackEvent, s as ValueExperimentInput, m as ValueVariantInput } from './types-0c_5qhVX.js';
3
3
 
4
4
  declare class ConfigError extends Error {
5
5
  constructor(message: string);
@@ -138,7 +138,41 @@ declare function newId(prefix?: string): string;
138
138
  declare function newVisitorId(): string;
139
139
  declare function newSessionId(): string;
140
140
 
141
+ /**
142
+ * Synchronous key-value storage, so assignment stays synchronous. React Native preloads
143
+ * AsyncStorage into memory or uses MMKV; native SDKs use UserDefaults / SharedPreferences.
144
+ */
145
+ interface KeyValueStorage {
146
+ getItem(key: string): string | null;
147
+ setItem(key: string, value: string): void;
148
+ removeItem(key: string): void;
149
+ }
150
+ /**
151
+ * What an app gives the client instead of a browser page. With it the client is a persistent
152
+ * client: no cookies, no `location` / `history` / `document`, no sendBeacon, and pageviews come
153
+ * only from `screen()` calls.
154
+ */
155
+ interface PlatformAdapter {
156
+ /** Persistent: visitor id, user id, the overrides cache and the offline queue. */
157
+ storage: KeyValueStorage;
158
+ /** Per launch: session id, exposures already sent. Defaults to an in-memory map. */
159
+ session?: KeyValueStorage;
160
+ /** Attached to every batch. */
161
+ app?: AppInfo;
162
+ /** Platform, appVersion, language, timezone, device, os. `platform` / `appVersion` default to `app`'s. */
163
+ context?: TargetingContext;
164
+ /** The app went to the background: the client flushes the queue and closes the screen's engagement. Returns an unsubscribe function. */
165
+ onBackground?(cb: () => void): () => void;
166
+ /** The app came back: after 30 minutes away a new session starts. Returns an unsubscribe function. */
167
+ onForeground?(cb: () => void): () => void;
168
+ }
169
+ /** A storage that lives as long as the process: the default `session` of an adapter, and handy in tests. */
170
+ declare function memoryStorage(initial?: Record<string, string>): KeyValueStorage;
171
+
172
+ /** A web page. React Native has a `window` but no page (and `navigator.product` says so). */
141
173
  declare const isBrowser: () => boolean;
174
+ /** React Native (Hermes or JSC): a `window` and a `navigator`, but no page. */
175
+ declare const isReactNative: () => boolean;
142
176
  /**
143
177
  * Visitor id lookup order: cookie → localStorage → new. The value is written
144
178
  * to both so that SSR (cookie) and SPA (localStorage) agree.
@@ -154,6 +188,12 @@ declare const TARGET_OPS: TargetOp[];
154
188
  declare const KEYED_FIELDS: TargetField[];
155
189
  /** Value of a context field as a lowercase string, or undefined when unknown. */
156
190
  declare function contextValue(field: TargetField, key: string | undefined, ctx: TargetingContext): string | undefined;
191
+ /**
192
+ * Orders two versions: dotted parts compare as numbers when both are digits
193
+ * (`2.10.0` > `2.9`), otherwise as strings; a missing part counts as 0, so
194
+ * `2.0` equals `2`. Plain numbers are one-part versions. Native SDKs port this as is.
195
+ */
196
+ declare function compareVersions(a: string, b: string): number;
157
197
  declare function evaluateCondition(c: TargetCondition, ctx: TargetingContext): boolean;
158
198
  declare function matchConditions(conditions: TargetCondition[], match: 'all' | 'any', ctx: TargetingContext): boolean;
159
199
  type FlowOutcome = {
@@ -244,6 +284,8 @@ interface TransportOptions {
244
284
  * `fetch(..., { keepalive: true })` on page hide, which also outlives the page.
245
285
  */
246
286
  keyInQuery?: boolean;
287
+ /** `fetch(..., { keepalive })`; default true. Apps pass false: there is no page to outlive. */
288
+ keepalive?: boolean;
247
289
  }
248
290
  /** Default transport: fetch with keepalive; sendBeacon on page hide when the endpoint allows it. */
249
291
  declare function createFetchTransport(options: TransportOptions): Transport;
@@ -255,12 +297,24 @@ interface EventQueueOptions {
255
297
  maxBatch?: number;
256
298
  /** Flush at least this often (ms). Default 2000. */
257
299
  flushInterval?: number;
258
- /** Events kept while the endpoint is unreachable; the oldest go first. Default 200. */
300
+ /** Events kept while the endpoint is unreachable; the oldest go first. Default 200, 1000 with `storage`. */
259
301
  maxQueue?: number;
260
- /** Attempts per event before it is dropped. Default 5. */
302
+ /**
303
+ * Attempts per event before it is dropped. Default 5. With `storage`, network failures and
304
+ * 5xx / 408 never use up attempts; a 429 always does (the project is throttled, over quota or gone).
305
+ */
261
306
  maxAttempts?: number;
307
+ /**
308
+ * Apps: unsent events are kept here (key `sh_queue`), so they survive a restart and an offline
309
+ * stretch; network failures and 5xx / 408 back off up to 60 s. Queues sharing one storage share
310
+ * `sh_queue`: only the first restores it, and each write carries every live queue's events.
311
+ */
312
+ storage?: KeyValueStorage;
313
+ /** Sent with every batch (apps). */
314
+ app?: AppInfo;
262
315
  onError?: (error: unknown) => void;
263
316
  }
317
+ declare const QUEUE_STORAGE_KEY = "sh_queue";
264
318
  /**
265
319
  * Batches events and sends them on a timer, when a batch is full, and when the page is
266
320
  * hidden (sendBeacon / keepalive). A failed batch is retried with exponential backoff and
@@ -272,7 +326,12 @@ declare class EventQueue {
272
326
  private readonly options;
273
327
  private pending;
274
328
  private retry;
329
+ /** Batches on their way: still persisted until the transport says they arrived. */
330
+ private readonly inflight;
275
331
  private attempts;
332
+ /** 429s in a row: they drop the batch after `maxAttempts`, storage or not. */
333
+ private throttled;
334
+ private destroyed;
276
335
  private timer;
277
336
  private backoffUntil;
278
337
  private readonly maxBatch;
@@ -281,6 +340,9 @@ declare class EventQueue {
281
340
  private readonly maxAttempts;
282
341
  private unbind;
283
342
  constructor(options: EventQueueOptions);
343
+ /** Hands over the events waiting here (not those on their way) to a queue that adopts them. */
344
+ private release;
345
+ private persist;
284
346
  private bind;
285
347
  private schedule;
286
348
  push(event: SplitHubEvent): void;
@@ -334,27 +396,44 @@ declare const EMPTY_OVERRIDES: RemoteOverrides;
334
396
  /** Pure merge: returns a new config, never mutates the input. */
335
397
  declare function applyRemoteOverrides(config: SplitHubConfig, overrides: RemoteOverrides | null | undefined): SplitHubConfig;
336
398
  declare function isRemoteOverrides(value: unknown): value is RemoteOverrides;
337
- /** `https://go.splithub.io/v1/events` → `https://go.splithub.io/v1/overrides/<pk>.json` */
338
- declare function resolveOverridesUrl(eventsEndpoint: string, publicKey: string): string;
399
+ /**
400
+ * `https://go.splithub.io/v1/events` → `https://go.splithub.io/v1/overrides/<pk>.json`.
401
+ * `all` (apps: clients with a platform adapter) also asks for every experiment pushed from
402
+ * `splithub.config.ts`: an app has no config file to learn them from. Websites never ask for it.
403
+ */
404
+ declare function resolveOverridesUrl(eventsEndpoint: string, publicKey: string, all?: boolean): string;
339
405
  interface CacheEntry {
340
406
  fetchedAt: number;
341
407
  overrides: RemoteOverrides;
342
408
  }
343
409
  declare const REMOTE_TTL_MS = 60000;
344
- declare function readRemoteCache(publicKey: string): CacheEntry | null;
345
- declare function writeRemoteCache(publicKey: string, overrides: RemoteOverrides): void;
410
+ declare function readRemoteCache(publicKey: string, store?: KeyValueStorage | null, all?: boolean): CacheEntry | null;
411
+ declare function writeRemoteCache(publicKey: string, overrides: RemoteOverrides, store?: KeyValueStorage | null, all?: boolean): void;
346
412
  declare function fetchRemoteOverrides(url: string, fetchImpl?: typeof fetch): Promise<RemoteOverrides | null>;
347
413
 
348
414
  declare const SDK_VERSION = "0.1.0";
349
- /** First visit without cached overrides: the longest the client waits for them. The fetch usually takes ~150 ms. */
415
+ /**
416
+ * First visit (or first app launch) without cached overrides: the longest the client waits for
417
+ * them. The fetch usually takes ~150 ms. Apps wait the same: later launches read the cache.
418
+ */
350
419
  declare const REMOTE_WAIT_MS = 400;
351
420
  declare const CLOUD_ENDPOINT = "https://go.splithub.io/v1/events";
421
+ /** An app away this long starts a new session when it comes back. */
422
+ declare const SESSION_GAP_MS: number;
352
423
  interface ClientOptions {
353
424
  /** Provide on the server (from the cookie) so SSR and client agree. */
354
425
  visitorId?: string;
355
426
  sessionId?: string;
356
427
  /** Custom transport, e.g. a no-op for tests or SSR. */
357
428
  transport?: Transport;
429
+ /**
430
+ * Apps (React Native, desktop): storage, app info and lifecycle instead of a browser page.
431
+ * The client then keeps the visitor in `storage`, persists unsent events (`sh_queue`), sends
432
+ * no pageviews of its own (call `screen()`), and starts a new session after 30 minutes in the background.
433
+ */
434
+ platform?: PlatformAdapter;
435
+ /** `sdk` of every batch. Default `core/<version>`; wrappers name themselves (`react-native/1.0.0`). */
436
+ sdk?: string;
358
437
  /**
359
438
  * Send the cloud key as `?key=` so page-hide batches can use `navigator.sendBeacon`.
360
439
  * On by default for SplitHub Cloud (the key is public); off for a custom endpoint,
@@ -413,6 +492,7 @@ interface ClientOptions {
413
492
  interface SplitHubClient {
414
493
  readonly config: SplitHubConfig;
415
494
  readonly visitorId: string;
495
+ /** May change during the client's life (an app back after 30 minutes away): read it each time, do not keep a copy. */
416
496
  readonly sessionId: string;
417
497
  /** Targeting context used for assignments. */
418
498
  readonly context: TargetingContext;
@@ -445,6 +525,12 @@ interface SplitHubClient {
445
525
  * of the URL. Without a property, the goal rows of the URL go out instead.
446
526
  */
447
527
  pageview(path?: string): void;
528
+ /**
529
+ * A screen of an app (or a virtual page on the web): a `page` event with url `/${name}` (or
530
+ * `name` itself when it starts with `/`) and the name as title. `props` are accepted for
531
+ * later; page rows carry none on the wire yet.
532
+ */
533
+ screen(name: string, props?: Record<string, unknown>): void;
448
534
  /**
449
535
  * Ties this visitor to your user id (1..128 characters) with optional flat traits
450
536
  * (`{ plan: 'pro' }`). Remembered in the browser and re-sent once per session; `null` forgets it.
@@ -454,6 +540,11 @@ interface SplitHubClient {
454
540
  autoGoals(root?: Document | HTMLElement): () => void;
455
541
  flush(): Promise<void>;
456
542
  destroy(): void;
543
+ /**
544
+ * Binds the app lifecycle (background / foreground) again after `destroy()`, as a provider does when
545
+ * StrictMode mounts it a second time. Idempotent; a no-op on the web, where the next event binds.
546
+ */
547
+ resume(): void;
457
548
  }
458
549
  declare function createClient(config: SplitHubConfig, options?: ClientOptions): SplitHubClient;
459
550
 
@@ -471,4 +562,4 @@ declare function debugLog(kind: DebugKind, message: string, data?: Record<string
471
562
  /** Subscribe to debug entries (the devtools panel). Returns an unsubscribe function. */
472
563
  declare function onDebug(listener: (e: DebugEntry) => void): () => void;
473
564
 
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 };
565
+ export { AppInfo, 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, type KeyValueStorage, LAYER_BUCKETS, MVT_MAX_COMBINATIONS, MVT_MAX_FACTORS, MVT_MAX_LEVELS, PROPERTY_KEY_PATTERN, type PlatformAdapter, Property, PropertyInput, PropertyStatus, QUEUE_STORAGE_KEY, REMOTE_TTL_MS, REMOTE_WAIT_MS, type RedirectDecision, type RemoteOverrides, SDK_VERSION, SESSION_GAP_MS, type SplitHubClient, SplitHubConfig, SplitHubConfigInput, SplitHubEvent, TARGET_FIELDS, TARGET_OPS, TargetCondition, TargetField, TargetOp, TargetingContext, type Transport, type TransportOptions, Variant, applyRemoteOverrides, assign, browserContext, compareVersions, 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, isReactNative, isRemoteOverrides, isSplitHubConfig, layerBucket, matchConditions, matchPath, measuredGoals, memoryStorage, 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
@@ -11,14 +11,17 @@ import {
11
11
  MVT_MAX_FACTORS,
12
12
  MVT_MAX_LEVELS,
13
13
  PROPERTY_KEY_PATTERN,
14
+ QUEUE_STORAGE_KEY,
14
15
  REMOTE_TTL_MS,
15
16
  REMOTE_WAIT_MS,
16
17
  SDK_VERSION,
18
+ SESSION_GAP_MS,
17
19
  TARGET_FIELDS,
18
20
  TARGET_OPS,
19
21
  applyRemoteOverrides,
20
22
  assign,
21
23
  browserContext,
24
+ compareVersions,
22
25
  contextValue,
23
26
  controlVariant,
24
27
  countsForHoldout,
@@ -49,12 +52,14 @@ import {
49
52
  isDebug,
50
53
  isDevDraft,
51
54
  isDevEnvironment,
55
+ isReactNative,
52
56
  isRemoteOverrides,
53
57
  isSplitHubConfig,
54
58
  layerBucket,
55
59
  matchConditions,
56
60
  matchPath,
57
61
  measuredGoals,
62
+ memoryStorage,
58
63
  murmur3,
59
64
  mvtVariants,
60
65
  newId,
@@ -78,7 +83,7 @@ import {
78
83
  runFlow,
79
84
  validateFlow,
80
85
  writeRemoteCache
81
- } from "./chunk-7CE2FI5Y.js";
86
+ } from "./chunk-O4D5SUSA.js";
82
87
 
83
88
  // src/redirect.ts
84
89
  function decideRedirect(config, pathname, visitorId, context = {}, overrides = {}, explain) {
@@ -110,14 +115,17 @@ export {
110
115
  MVT_MAX_FACTORS,
111
116
  MVT_MAX_LEVELS,
112
117
  PROPERTY_KEY_PATTERN,
118
+ QUEUE_STORAGE_KEY,
113
119
  REMOTE_TTL_MS,
114
120
  REMOTE_WAIT_MS,
115
121
  SDK_VERSION,
122
+ SESSION_GAP_MS,
116
123
  TARGET_FIELDS,
117
124
  TARGET_OPS,
118
125
  applyRemoteOverrides,
119
126
  assign,
120
127
  browserContext,
128
+ compareVersions,
121
129
  contextValue,
122
130
  controlVariant,
123
131
  countsForHoldout,
@@ -149,12 +157,14 @@ export {
149
157
  isDebug,
150
158
  isDevDraft,
151
159
  isDevEnvironment,
160
+ isReactNative,
152
161
  isRemoteOverrides,
153
162
  isSplitHubConfig,
154
163
  layerBucket,
155
164
  matchConditions,
156
165
  matchPath,
157
166
  measuredGoals,
167
+ memoryStorage,
158
168
  murmur3,
159
169
  mvtVariants,
160
170
  newId,
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":[]}
@@ -17,14 +17,18 @@ type RedirectVariantInput = {
17
17
  weight: number;
18
18
  to: string;
19
19
  };
20
- type TargetField = 'country' | 'region' | 'city' | 'device' | 'browser' | 'os' | 'language' | 'referrer' | 'url' | 'path' | 'query' | 'utm_source' | 'utm_medium' | 'utm_campaign' | 'utm_term' | 'utm_content' | 'cookie' | 'visitor' | 'hour' | 'weekday';
21
- type TargetOp = 'is' | 'is_not' | 'contains' | 'not_contains' | 'starts_with' | 'in' | 'not_in' | 'matches' | 'exists' | 'not_exists';
20
+ type TargetField = 'country' | 'region' | 'city' | 'device' | 'browser' | 'os' | 'language' | 'referrer' | 'url' | 'path' | 'query' | 'utm_source' | 'utm_medium' | 'utm_campaign' | 'utm_term' | 'utm_content' | 'cookie' | 'visitor' | 'hour' | 'weekday'
21
+ /** `web`, `ios`, `android`, `macos`, `windows`, `linux` (apps report theirs; the browser is `web`). */
22
+ | 'platform'
23
+ /** The app's version (`2.4.1`); compare with `gte` / `lt`. Absent on websites. */
24
+ | 'app_version';
25
+ type TargetOp = 'is' | 'is_not' | 'contains' | 'not_contains' | 'starts_with' | 'in' | 'not_in' | 'matches' | 'exists' | 'not_exists' | 'gte' | 'lt';
22
26
  interface TargetCondition {
23
27
  field: TargetField;
24
28
  op: TargetOp;
25
29
  /** Parameter / cookie name for `query` and `cookie`. */
26
30
  key?: string;
27
- /** Comparison value; comma-separated list for `in` / `not_in`; regex for `matches`. */
31
+ /** Comparison value; comma-separated list for `in` / `not_in`; regex for `matches`; a version or number for `gte` / `lt` (dotted versions compare part by part). */
28
32
  value?: string;
29
33
  }
30
34
  type FlowNode = {
@@ -78,7 +82,12 @@ interface TargetingContext {
78
82
  * fills it from the device; on the server it comes from geo headers. Without it, UTC.
79
83
  */
80
84
  timezone?: string;
85
+ /** `web` in the browser; an app reports its platform (`ios`, `android` ...). */
86
+ platform?: AppPlatform;
87
+ /** The app's version, for `app_version` conditions. */
88
+ appVersion?: string;
81
89
  }
90
+ type AppPlatform = 'web' | 'ios' | 'android' | 'macos' | 'windows' | 'linux';
82
91
  interface ExperimentBase {
83
92
  status: ExperimentStatus;
84
93
  /** Targeting / branching graph. Omit to use plain weights for everyone. */
@@ -214,7 +223,10 @@ interface PropertyInput {
214
223
  description?: string;
215
224
  /** Goal keys from `goals` reported as conversions of this property. Default: every goal of the project. */
216
225
  goals?: string[];
226
+ /** What the property measures: a website (default) or an app (screens instead of pages, versions, retention). */
227
+ kind?: PropertyKind;
217
228
  }
229
+ type PropertyKind = 'site' | 'app';
218
230
  type PropertyStatus = 'running' | 'paused';
219
231
  interface SplitHubConfigInput {
220
232
  project: string;
@@ -339,6 +351,8 @@ interface Property {
339
351
  goals: string[];
340
352
  /** Where the property was defined: the config file (default) or the cloud dashboard. */
341
353
  origin?: 'config' | 'dashboard';
354
+ /** Default `site`. */
355
+ kind?: PropertyKind;
342
356
  }
343
357
  interface SplitHubConfig {
344
358
  project: string;
@@ -434,10 +448,30 @@ interface IdentifyEvent {
434
448
  traits?: Record<string, string | number | boolean>;
435
449
  }
436
450
  type SplitHubEvent = ExposureEvent | GoalEvent | PageEvent | TrackEvent | EngageEvent | IdentifyEvent;
451
+ /**
452
+ * Who sends a batch from an app (absent from websites). The cloud takes the device, OS and
453
+ * platform from here instead of the user agent, and `id` stands in for the origin: an allowed
454
+ * domain list may name the app's bundle id / package name.
455
+ */
456
+ interface AppInfo {
457
+ platform: Exclude<AppPlatform, 'web'>;
458
+ /** Bundle id / application id (`com.acme.shop`), up to 128 characters. */
459
+ id?: string;
460
+ /** Marketing version (`2.4.1`), up to 32 characters. */
461
+ version?: string;
462
+ /** Build number (`412`), up to 32 characters. */
463
+ build?: string;
464
+ /** OS version (`18.1`), up to 32 characters. */
465
+ os?: string;
466
+ /** Device model (`iPhone15,2`, `Pixel 8`), up to 64 characters. */
467
+ model?: string;
468
+ device?: 'mobile' | 'tablet' | 'desktop';
469
+ }
437
470
  interface EventBatch {
438
471
  project: string;
439
472
  sdk: string;
440
473
  events: SplitHubEvent[];
474
+ app?: AppInfo;
441
475
  }
442
476
  interface Assignment {
443
477
  experiment: string;
@@ -451,4 +485,4 @@ interface Assignment {
451
485
  reason: 'assigned' | 'dev' | 'not_running' | 'outside_traffic' | 'unknown_experiment' | 'override' | 'targeting' | 'bot' | 'no_visitor' | 'layer' | 'holdout' | 'pending';
452
486
  }
453
487
 
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 };
488
+ export type { Assignment as A, ExposureEvent as B, ComponentVariantInput as C, GoalEvent as D, Experiment as E, Factor as F, Goal as G, Holdout as H, PageEvent as I, TrackEvent as J, EngageEvent as K, IdentifyEvent as L, MvtExperimentInput as M, PropertyInput as P, RedirectVariantInput as R, SplitHubConfigInput as S, TargetingContext as T, Variant as V, SplitHubConfig as a, Property as b, AppInfo as c, Flow as d, TargetCondition as e, TargetField as f, TargetOp as g, EventBatch as h, SplitHubEvent as i, ExperimentStatus as j, PropertyStatus as k, ExperimentKind as l, ValueVariantInput as m, FlowNode as n, AppPlatform as o, ExperimentBase as p, GuardrailInput as q, ComponentExperimentInput as r, ValueExperimentInput as s, RedirectExperimentInput as t, ExperimentInput as u, GoalLabels as v, GoalInput as w, StorageInput as x, PropertyKind as y, ExperimentMetrics as z };