@splithub/node 0.4.2 → 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,4 +1,4 @@
1
- import { SplitHubConfig, Experiment, Goal } from '@splithub/core';
1
+ import { SplitHubConfig, Experiment, AppInfo, 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. */
@@ -104,6 +104,10 @@ interface StoredEvent {
104
104
  utm_campaign?: string | null;
105
105
  utm_term?: string | null;
106
106
  utm_content?: string | null;
107
+ /** `web` for website batches, else the app's platform (`ios`, `android`, `macos`, `windows`, `linux`). */
108
+ platform?: string | null;
109
+ /** The app's version (`2.4.1`); null on websites. */
110
+ app_version?: string | null;
107
111
  }
108
112
  interface ExperimentSummary {
109
113
  experiment: string;
@@ -339,12 +343,26 @@ type ValidationResult = {
339
343
  events: StoredEvent[];
340
344
  dropped: number;
341
345
  errors: string[];
346
+ app?: AppInfo;
342
347
  } | {
343
348
  ok: false;
344
349
  error: string;
345
350
  };
346
351
  /** `expectedProject` null skips the name check (the caller already identified the project, e.g. by public key). */
347
352
  declare function validateBatch(body: unknown, expectedProject: string | null, now?: number): ValidationResult;
353
+ /** The batch's `app` block, trimmed to its limits; undefined for websites or an unknown platform (the batch is then read as a website's). */
354
+ declare function sanitizeApp(raw: unknown): AppInfo | undefined;
355
+
356
+ /** The stored dimensions a batch's `app` block stands for. Same mapping as the cloud ingest. */
357
+ type AppDimensions = Pick<StoredEvent, 'platform' | 'app_version'> & Partial<Pick<StoredEvent, 'device' | 'os' | 'browser' | 'host'>>;
358
+ /**
359
+ * `platform` is `web` and `app_version` null for websites. An app batch replaces the user agent:
360
+ * device from `app.device` (default `mobile`), OS from the platform, browser `App`, and the app id
361
+ * stands in for the origin host (apps send no Origin).
362
+ */
363
+ declare function appDimensions(app: AppInfo | undefined): AppDimensions;
364
+ /** The batch's events with the app dimensions stamped on (an ingest-supplied host wins over the app id). */
365
+ declare function withAppDimensions(events: StoredEvent[], app: AppInfo | undefined): StoredEvent[];
348
366
 
349
367
  interface ConformanceCase {
350
368
  name: string;
@@ -386,4 +404,4 @@ type DerivedGoal = StoredEvent & {
386
404
  /** Goal rows derived from the batch's `event` and `page` rows (see the rule above). */
387
405
  declare function goalsFromAnalytics(events: readonly StoredEvent[], goals: readonly DerivableGoal[]): DerivedGoal[];
388
406
 
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 };
407
+ export { ANALYSIS_UNAVAILABLE, ANALYTICS_TYPES, ATTRIBUTION_SKEW_MS, type AppDimensions, 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, appDimensions, attributeVariants, attributionConformance, countProperty, countsFromRow, createMemoryStore, createSplitHubHandler, experimentGoals, goalsFromAnalytics, propertyCountsFromRows, propertyCountsSql, rawPropertyRange, rawPropertyReport, rawResults, rawStatusTable, resultsExperiment, revenueOf, sanitizeApp, sortCounts, storedEventFromRow, toNodeListener, validateBatch, variantCountsSql, withAppDimensions };
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { SplitHubConfig, Experiment, Goal } from '@splithub/core';
1
+ import { SplitHubConfig, Experiment, AppInfo, 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. */
@@ -104,6 +104,10 @@ interface StoredEvent {
104
104
  utm_campaign?: string | null;
105
105
  utm_term?: string | null;
106
106
  utm_content?: string | null;
107
+ /** `web` for website batches, else the app's platform (`ios`, `android`, `macos`, `windows`, `linux`). */
108
+ platform?: string | null;
109
+ /** The app's version (`2.4.1`); null on websites. */
110
+ app_version?: string | null;
107
111
  }
108
112
  interface ExperimentSummary {
109
113
  experiment: string;
@@ -339,12 +343,26 @@ type ValidationResult = {
339
343
  events: StoredEvent[];
340
344
  dropped: number;
341
345
  errors: string[];
346
+ app?: AppInfo;
342
347
  } | {
343
348
  ok: false;
344
349
  error: string;
345
350
  };
346
351
  /** `expectedProject` null skips the name check (the caller already identified the project, e.g. by public key). */
347
352
  declare function validateBatch(body: unknown, expectedProject: string | null, now?: number): ValidationResult;
353
+ /** The batch's `app` block, trimmed to its limits; undefined for websites or an unknown platform (the batch is then read as a website's). */
354
+ declare function sanitizeApp(raw: unknown): AppInfo | undefined;
355
+
356
+ /** The stored dimensions a batch's `app` block stands for. Same mapping as the cloud ingest. */
357
+ type AppDimensions = Pick<StoredEvent, 'platform' | 'app_version'> & Partial<Pick<StoredEvent, 'device' | 'os' | 'browser' | 'host'>>;
358
+ /**
359
+ * `platform` is `web` and `app_version` null for websites. An app batch replaces the user agent:
360
+ * device from `app.device` (default `mobile`), OS from the platform, browser `App`, and the app id
361
+ * stands in for the origin host (apps send no Origin).
362
+ */
363
+ declare function appDimensions(app: AppInfo | undefined): AppDimensions;
364
+ /** The batch's events with the app dimensions stamped on (an ingest-supplied host wins over the app id). */
365
+ declare function withAppDimensions(events: StoredEvent[], app: AppInfo | undefined): StoredEvent[];
348
366
 
349
367
  interface ConformanceCase {
350
368
  name: string;
@@ -386,4 +404,4 @@ type DerivedGoal = StoredEvent & {
386
404
  /** Goal rows derived from the batch's `event` and `page` rows (see the rule above). */
387
405
  declare function goalsFromAnalytics(events: readonly StoredEvent[], goals: readonly DerivableGoal[]): DerivedGoal[];
388
406
 
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 };
407
+ export { ANALYSIS_UNAVAILABLE, ANALYTICS_TYPES, ATTRIBUTION_SKEW_MS, type AppDimensions, 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, appDimensions, attributeVariants, attributionConformance, countProperty, countsFromRow, createMemoryStore, createSplitHubHandler, experimentGoals, goalsFromAnalytics, propertyCountsFromRows, propertyCountsSql, rawPropertyRange, rawPropertyReport, rawResults, rawStatusTable, resultsExperiment, revenueOf, sanitizeApp, sortCounts, storedEventFromRow, toNodeListener, validateBatch, variantCountsSql, withAppDimensions };
package/dist/index.js CHANGED
@@ -140,7 +140,10 @@ function storedEventFromRow(r) {
140
140
  host: s(r.host),
141
141
  country: s(r.country),
142
142
  device: s(r.device),
143
- browser: s(r.browser)
143
+ browser: s(r.browser),
144
+ // Columns added for apps; rows of stores without them keep the old shape.
145
+ ..."platform" in r ? { platform: s(r.platform) } : {},
146
+ ..."app_version" in r ? { app_version: s(r.app_version) } : {}
144
147
  };
145
148
  }
146
149
  var PROPERTY_REPORTS_UNAVAILABLE = {
@@ -407,7 +410,33 @@ function validateBatch(body, expectedProject, now = Date.now()) {
407
410
  if (errors.length < 5 && !errors.includes(e)) errors.push(e);
408
411
  } else out.push(e);
409
412
  }
410
- return { ok: true, events: out, dropped, errors };
413
+ const app = sanitizeApp(batch.app);
414
+ return { ok: true, events: out, dropped, errors, ...app ? { app } : {} };
415
+ }
416
+ var APP_PLATFORMS = /* @__PURE__ */ new Set(["ios", "android", "macos", "windows", "linux"]);
417
+ var APP_DEVICES = /* @__PURE__ */ new Set(["mobile", "tablet", "desktop"]);
418
+ function text(value, max) {
419
+ if (typeof value !== "string") return void 0;
420
+ const t = value.trim();
421
+ return t ? t.slice(0, max) : void 0;
422
+ }
423
+ function sanitizeApp(raw) {
424
+ if (!raw || typeof raw !== "object") return void 0;
425
+ const a = raw;
426
+ if (typeof a.platform !== "string" || !APP_PLATFORMS.has(a.platform)) return void 0;
427
+ const out = { platform: a.platform };
428
+ const id = text(a.id, 128);
429
+ const version = text(a.version, 32);
430
+ const build = text(a.build, 32);
431
+ const os = text(a.os, 32);
432
+ const model = text(a.model, 64);
433
+ if (id) out.id = id.toLowerCase();
434
+ if (version) out.version = version;
435
+ if (build) out.build = build;
436
+ if (os) out.os = os;
437
+ if (model) out.model = model;
438
+ if (typeof a.device === "string" && APP_DEVICES.has(a.device)) out.device = a.device;
439
+ return out;
411
440
  }
412
441
  function normalize(e, now) {
413
442
  if (!e || typeof e !== "object") return "event must be an object";
@@ -529,6 +558,17 @@ function goalsFromAnalytics(events, goals) {
529
558
  return out;
530
559
  }
531
560
 
561
+ // src/app.ts
562
+ var APP_OS = { ios: "iOS", android: "Android", macos: "macOS", windows: "Windows", linux: "Linux" };
563
+ function appDimensions(app) {
564
+ if (!app) return { platform: "web", app_version: null };
565
+ return { platform: app.platform, app_version: app.version ?? null, device: app.device ?? "mobile", os: APP_OS[app.platform], browser: "App", host: app.id ?? null };
566
+ }
567
+ function withAppDimensions(events, app) {
568
+ const d = appDimensions(app);
569
+ return events.map((e) => ({ ...e, ...d, ...e.host ? { host: e.host } : {} }));
570
+ }
571
+
532
572
  // src/handler.ts
533
573
  var isBotUserAgent = (ua) => isCrawler(ua);
534
574
  var visitorUserAgent = (request) => request.headers.get("x-splithub-ua") ?? request.headers.get("user-agent");
@@ -571,8 +611,9 @@ function createSplitHubHandler(options) {
571
611
  const received = result.events.length + result.dropped;
572
612
  if (isBotUserAgent(visitorUserAgent(request))) return json(request, { ok: true, received, inserted: 0, ...dropped }, 202);
573
613
  const running = new Set((config.properties ?? []).filter((p) => p.status === "running").map((p) => p.key));
574
- const derived = goalsFromAnalytics(result.events, derivable).map(({ derived: _, ...goal2 }) => goal2);
575
- const events = [...result.events.filter((e) => !ANALYTICS_TYPES.has(e.type) || e.experiment !== null && running.has(e.experiment)), ...derived];
614
+ const stamped = withAppDimensions(result.events, result.app);
615
+ const derived = goalsFromAnalytics(stamped, derivable).map(({ derived: _, ...goal2 }) => goal2);
616
+ const events = [...stamped.filter((e) => !ANALYTICS_TYPES.has(e.type) || e.experiment !== null && running.has(e.experiment)), ...derived];
576
617
  const inserted = events.length ? await store.insertEvents(events) : 0;
577
618
  return json(request, { ok: true, received, inserted, ...dropped }, 202);
578
619
  }
@@ -764,6 +805,7 @@ export {
764
805
  GOAL_DAILY_CAP,
765
806
  PROPERTY_REPORTS_UNAVAILABLE,
766
807
  SAME_ACTION_MS,
808
+ appDimensions,
767
809
  attributeVariants,
768
810
  attributionConformance,
769
811
  countProperty,
@@ -780,10 +822,12 @@ export {
780
822
  rawStatusTable,
781
823
  resultsExperiment,
782
824
  revenueOf,
825
+ sanitizeApp,
783
826
  sortCounts,
784
827
  storedEventFromRow,
785
828
  toNodeListener,
786
829
  validateBatch,
787
- variantCountsSql
830
+ variantCountsSql,
831
+ withAppDimensions
788
832
  };
789
833
  //# sourceMappingURL=index.js.map