@10x-media/analytics 0.1.0-beta.4 → 1.0.0-beta.10

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.
Files changed (521) hide show
  1. package/CHANGELOG.md +280 -0
  2. package/LICENSE +21 -21
  3. package/README.md +15 -4
  4. package/dist/adapters/ga4/disableKey.d.ts +9 -0
  5. package/dist/adapters/ga4/disableKey.js +21 -0
  6. package/dist/adapters/ga4/disableKey.js.map +1 -0
  7. package/dist/adapters/ga4/eventName.d.ts +15 -0
  8. package/dist/adapters/ga4/eventName.js +19 -0
  9. package/dist/adapters/ga4/eventName.js.map +1 -0
  10. package/dist/adapters/ga4/ga4.d.ts +5 -0
  11. package/dist/adapters/ga4/ga4.js +186 -58
  12. package/dist/adapters/ga4/ga4.js.map +1 -1
  13. package/dist/adapters/ga4/measurementId.js +15 -0
  14. package/dist/adapters/ga4/measurementId.js.map +1 -0
  15. package/dist/adapters/goalRead.js +126 -0
  16. package/dist/adapters/goalRead.js.map +1 -0
  17. package/dist/adapters/http/fetchJson.js +1 -1
  18. package/dist/adapters/plausible/plausible.d.ts +25 -0
  19. package/dist/adapters/plausible/plausible.js +159 -38
  20. package/dist/adapters/plausible/plausible.js.map +1 -1
  21. package/dist/adapters/posthog/posthog.d.ts +10 -1
  22. package/dist/adapters/posthog/posthog.js +130 -21
  23. package/dist/adapters/posthog/posthog.js.map +1 -1
  24. package/dist/adapters/series.js +11 -1
  25. package/dist/adapters/series.js.map +1 -1
  26. package/dist/adapters/umami/umami.d.ts +13 -1
  27. package/dist/adapters/umami/umami.js +278 -26
  28. package/dist/adapters/umami/umami.js.map +1 -1
  29. package/dist/binding/resolvePath.js +18 -2
  30. package/dist/binding/resolvePath.js.map +1 -1
  31. package/dist/capture/getTrackerConfig.d.ts +20 -0
  32. package/dist/capture/getTrackerConfig.js +31 -0
  33. package/dist/capture/getTrackerConfig.js.map +1 -0
  34. package/dist/capture/mountPath.js +14 -0
  35. package/dist/capture/mountPath.js.map +1 -0
  36. package/dist/capture/proxyEndpoint.js +127 -0
  37. package/dist/capture/proxyEndpoint.js.map +1 -0
  38. package/dist/capture/proxyRoutes.js +108 -0
  39. package/dist/capture/proxyRoutes.js.map +1 -0
  40. package/dist/capture/requestBody.js +68 -0
  41. package/dist/capture/requestBody.js.map +1 -0
  42. package/dist/capture/slots.d.ts +8 -0
  43. package/dist/capture/slots.js +54 -0
  44. package/dist/capture/slots.js.map +1 -0
  45. package/dist/capture/trackerConfig.d.ts +33 -0
  46. package/dist/capture/trackerConfig.js +95 -0
  47. package/dist/capture/trackerConfig.js.map +1 -0
  48. package/dist/capture/trackerEndpoint.js +35 -0
  49. package/dist/capture/trackerEndpoint.js.map +1 -0
  50. package/dist/charts/BarList.d.ts +16 -1
  51. package/dist/charts/BarList.js +41 -19
  52. package/dist/charts/BarList.js.map +1 -1
  53. package/dist/charts/TrendChart.d.ts +16 -3
  54. package/dist/charts/TrendChart.js +172 -106
  55. package/dist/charts/TrendChart.js.map +1 -1
  56. package/dist/charts/bars.d.ts +4 -0
  57. package/dist/charts/bars.js +3 -1
  58. package/dist/charts/bars.js.map +1 -1
  59. package/dist/charts/bucket.js +10 -1
  60. package/dist/charts/bucket.js.map +1 -1
  61. package/dist/charts/spline.js +2 -2
  62. package/dist/charts/spline.js.map +1 -1
  63. package/dist/charts/styles.js +18 -1
  64. package/dist/charts/styles.js.map +1 -1
  65. package/dist/core/cacheKey.js +26 -3
  66. package/dist/core/cacheKey.js.map +1 -1
  67. package/dist/core/capabilities.d.ts +17 -2
  68. package/dist/core/capabilities.js +20 -1
  69. package/dist/core/capabilities.js.map +1 -1
  70. package/dist/core/capture.d.ts +49 -0
  71. package/dist/core/contract.d.ts +74 -5
  72. package/dist/core/contract.js +30 -1
  73. package/dist/core/contract.js.map +1 -1
  74. package/dist/core/granularity.js +1 -1
  75. package/dist/core/options.d.ts +168 -8
  76. package/dist/core/options.js +132 -4
  77. package/dist/core/options.js.map +1 -1
  78. package/dist/core/registry.d.ts +1 -0
  79. package/dist/core/scopeList.js +32 -0
  80. package/dist/core/scopeList.js.map +1 -0
  81. package/dist/core/scopedRead.js +101 -29
  82. package/dist/core/scopedRead.js.map +1 -1
  83. package/dist/core/serverEvent.d.ts +60 -0
  84. package/dist/core/serverEvent.js +12 -0
  85. package/dist/core/serverEvent.js.map +1 -0
  86. package/dist/exports/adapters/ga4.d.ts +2 -1
  87. package/dist/exports/adapters/ga4.js +2 -1
  88. package/dist/exports/adapters/native.d.ts +3 -1
  89. package/dist/exports/adapters/native.js +2 -1
  90. package/dist/exports/client.d.ts +16 -2
  91. package/dist/exports/client.js +13 -1
  92. package/dist/exports/geo.d.ts +2 -2
  93. package/dist/exports/next.d.ts +2 -1
  94. package/dist/exports/next.js +2 -1
  95. package/dist/exports/react.d.ts +4 -0
  96. package/dist/exports/react.js +5 -0
  97. package/dist/exports/rsc.d.ts +12 -4
  98. package/dist/exports/rsc.js +7 -2
  99. package/dist/exports/tracker.d.ts +21 -0
  100. package/dist/exports/tracker.js +15 -0
  101. package/dist/exports/types.d.ts +17 -3
  102. package/dist/exports/types.js +4 -2
  103. package/dist/fields/AnalyticsPanelClient.js +2 -2
  104. package/dist/fields/AnalyticsPanelField.js +1 -1
  105. package/dist/fields/AnalyticsStatField.js +2 -2
  106. package/dist/fields/config/FilterDimensionSelectField.d.ts +14 -0
  107. package/dist/fields/config/FilterDimensionSelectField.js +77 -0
  108. package/dist/fields/config/FilterDimensionSelectField.js.map +1 -0
  109. package/dist/fields/config/FilterOperatorSelectField.d.ts +14 -0
  110. package/dist/fields/config/FilterOperatorSelectField.js +75 -0
  111. package/dist/fields/config/FilterOperatorSelectField.js.map +1 -0
  112. package/dist/fields/config/MetricSelectField.d.ts +23 -0
  113. package/dist/fields/config/MetricSelectField.js +51 -0
  114. package/dist/fields/config/MetricSelectField.js.map +1 -0
  115. package/dist/fields/config/SourceSelectField.d.ts +14 -0
  116. package/dist/fields/config/SourceSelectField.js +46 -0
  117. package/dist/fields/config/SourceSelectField.js.map +1 -0
  118. package/dist/fields/config/fetchSources.d.ts +16 -0
  119. package/dist/fields/config/fetchSources.js +33 -0
  120. package/dist/fields/config/fetchSources.js.map +1 -0
  121. package/dist/fields/config/narrow.js +32 -0
  122. package/dist/fields/config/narrow.js.map +1 -0
  123. package/dist/fields/config/sourcesState.js +27 -0
  124. package/dist/fields/config/sourcesState.js.map +1 -0
  125. package/dist/fields/config/toSelectOption.js +27 -0
  126. package/dist/fields/config/toSelectOption.js.map +1 -0
  127. package/dist/fields/config/useAnalyticsSources.d.ts +24 -0
  128. package/dist/fields/config/useAnalyticsSources.js +62 -0
  129. package/dist/fields/config/useAnalyticsSources.js.map +1 -0
  130. package/dist/fields/config/useFilterCapabilities.d.ts +28 -0
  131. package/dist/fields/config/useFilterCapabilities.js +52 -0
  132. package/dist/fields/config/useFilterCapabilities.js.map +1 -0
  133. package/dist/fields/readForDocument.d.ts +5 -0
  134. package/dist/fields/readForDocument.js +22 -10
  135. package/dist/fields/readForDocument.js.map +1 -1
  136. package/dist/goals/GoalSelectField.d.ts +7 -0
  137. package/dist/goals/GoalSelectField.js +77 -0
  138. package/dist/goals/GoalSelectField.js.map +1 -0
  139. package/dist/goals/collection.js +254 -0
  140. package/dist/goals/collection.js.map +1 -0
  141. package/dist/goals/currency.js +14 -0
  142. package/dist/goals/currency.js.map +1 -0
  143. package/dist/goals/fetchGoals.d.ts +18 -0
  144. package/dist/goals/fetchGoals.js +33 -0
  145. package/dist/goals/fetchGoals.js.map +1 -0
  146. package/dist/goals/goalField.d.ts +31 -0
  147. package/dist/goals/goalField.js +56 -0
  148. package/dist/goals/goalField.js.map +1 -0
  149. package/dist/goals/goalsEndpoint.d.ts +1 -0
  150. package/dist/goals/goalsEndpoint.js +58 -0
  151. package/dist/goals/goalsEndpoint.js.map +1 -0
  152. package/dist/goals/match.js +64 -0
  153. package/dist/goals/match.js.map +1 -0
  154. package/dist/goals/resolver.d.ts +8 -0
  155. package/dist/goals/resolver.js +147 -0
  156. package/dist/goals/resolver.js.map +1 -0
  157. package/dist/goals/trackGoalAction.d.ts +76 -0
  158. package/dist/goals/trackGoalAction.js +158 -0
  159. package/dist/goals/trackGoalAction.js.map +1 -0
  160. package/dist/goals/types.d.ts +33 -0
  161. package/dist/goals/types.js +7 -0
  162. package/dist/goals/types.js.map +1 -0
  163. package/dist/goals/useAnalyticsGoals.d.ts +20 -0
  164. package/dist/goals/useAnalyticsGoals.js +67 -0
  165. package/dist/goals/useAnalyticsGoals.js.map +1 -0
  166. package/dist/index.d.ts +14 -3
  167. package/dist/index.js +185 -19
  168. package/dist/index.js.map +1 -1
  169. package/dist/native/collections/events.js +65 -1
  170. package/dist/native/collections/events.js.map +1 -1
  171. package/dist/native/collections/rollups.js +39 -3
  172. package/dist/native/collections/rollups.js.map +1 -1
  173. package/dist/native/eventScan.js +25 -0
  174. package/dist/native/eventScan.js.map +1 -0
  175. package/dist/native/geo/composeGeoResolvers.js +2 -2
  176. package/dist/native/geo/composeGeoResolvers.js.map +1 -1
  177. package/dist/native/geo/geoResolver.d.ts +9 -2
  178. package/dist/native/geo/geoResolver.js.map +1 -1
  179. package/dist/native/geo/maxmindResolver.js +3 -5
  180. package/dist/native/geo/maxmindResolver.js.map +1 -1
  181. package/dist/native/ingest/bots.d.ts +11 -0
  182. package/dist/native/ingest/bots.js +71 -0
  183. package/dist/native/ingest/bots.js.map +1 -0
  184. package/dist/native/ingest/browser.js +47 -0
  185. package/dist/native/ingest/browser.js.map +1 -0
  186. package/dist/native/ingest/clientIp.js +20 -0
  187. package/dist/native/ingest/clientIp.js.map +1 -0
  188. package/dist/native/ingest/device.js +11 -3
  189. package/dist/native/ingest/device.js.map +1 -1
  190. package/dist/native/ingest/endpoint.d.ts +1 -0
  191. package/dist/native/ingest/endpoint.js +107 -21
  192. package/dist/native/ingest/endpoint.js.map +1 -1
  193. package/dist/native/ingest/flushBatch.js +29 -38
  194. package/dist/native/ingest/flushBatch.js.map +1 -1
  195. package/dist/native/ingest/language.js +14 -0
  196. package/dist/native/ingest/language.js.map +1 -0
  197. package/dist/native/ingest/normalizeEvent.d.ts +30 -0
  198. package/dist/native/ingest/normalizeEvent.js +115 -16
  199. package/dist/native/ingest/normalizeEvent.js.map +1 -1
  200. package/dist/native/ingest/referrer.js +48 -0
  201. package/dist/native/ingest/referrer.js.map +1 -0
  202. package/dist/native/ingest/requestHost.js +57 -0
  203. package/dist/native/ingest/requestHost.js.map +1 -0
  204. package/dist/native/ingest/resolveHostname.d.ts +29 -0
  205. package/dist/native/ingest/resolveHostname.js +52 -0
  206. package/dist/native/ingest/resolveHostname.js.map +1 -0
  207. package/dist/native/ingest/salt.js +27 -2
  208. package/dist/native/ingest/salt.js.map +1 -1
  209. package/dist/native/ingest/serverTrack.d.ts +20 -0
  210. package/dist/native/ingest/serverTrack.js +109 -0
  211. package/dist/native/ingest/serverTrack.js.map +1 -0
  212. package/dist/native/ingest/source.d.ts +11 -0
  213. package/dist/native/ingest/source.js +264 -16
  214. package/dist/native/ingest/source.js.map +1 -1
  215. package/dist/native/ingest/utm.js +33 -0
  216. package/dist/native/ingest/utm.js.map +1 -0
  217. package/dist/native/ingest/validate.js +26 -0
  218. package/dist/native/ingest/validate.js.map +1 -0
  219. package/dist/native/nativeAdapter.d.ts +37 -1
  220. package/dist/native/nativeAdapter.js +175 -22
  221. package/dist/native/nativeAdapter.js.map +1 -1
  222. package/dist/native/query/eventAgg.js +175 -0
  223. package/dist/native/query/eventAgg.js.map +1 -0
  224. package/dist/native/retention/pruneTask.js +53 -13
  225. package/dist/native/retention/pruneTask.js.map +1 -1
  226. package/dist/native/rollupAcc.js +12 -1
  227. package/dist/native/rollupAcc.js.map +1 -1
  228. package/dist/native/rollups/bucketKey.js +15 -0
  229. package/dist/native/rollups/bucketKey.js.map +1 -0
  230. package/dist/native/rollups/bumpRollups.js +116 -0
  231. package/dist/native/rollups/bumpRollups.js.map +1 -0
  232. package/dist/native/rollups/deltas.js +86 -11
  233. package/dist/native/rollups/deltas.js.map +1 -1
  234. package/dist/native/rollups/insertManyIfNew.js +93 -0
  235. package/dist/native/rollups/insertManyIfNew.js.map +1 -0
  236. package/dist/next/captureRewrites.d.ts +42 -0
  237. package/dist/next/captureRewrites.js +57 -0
  238. package/dist/next/captureRewrites.js.map +1 -0
  239. package/dist/next/posthogProxyRewrites.d.ts +5 -0
  240. package/dist/next/posthogProxyRewrites.js +16 -21
  241. package/dist/next/posthogProxyRewrites.js.map +1 -1
  242. package/dist/plugin/documentEndpoint.js +71 -24
  243. package/dist/plugin/documentEndpoint.js.map +1 -1
  244. package/dist/plugin/errors.d.ts +31 -0
  245. package/dist/plugin/errors.js +79 -0
  246. package/dist/plugin/errors.js.map +1 -0
  247. package/dist/plugin/goalHint.d.ts +1 -0
  248. package/dist/plugin/goalHint.js +24 -0
  249. package/dist/plugin/goalHint.js.map +1 -0
  250. package/dist/plugin/paths.js +19 -1
  251. package/dist/plugin/paths.js.map +1 -1
  252. package/dist/plugin/queryEndpoint.js +124 -0
  253. package/dist/plugin/queryEndpoint.js.map +1 -0
  254. package/dist/plugin/readContextForRequest.js +73 -0
  255. package/dist/plugin/readContextForRequest.js.map +1 -0
  256. package/dist/plugin/realtimeEndpoint.js +39 -18
  257. package/dist/plugin/realtimeEndpoint.js.map +1 -1
  258. package/dist/plugin/refreshEndpoint.js +113 -0
  259. package/dist/plugin/refreshEndpoint.js.map +1 -0
  260. package/dist/plugin/runtime.d.ts +1 -0
  261. package/dist/plugin/runtime.js +33 -1
  262. package/dist/plugin/runtime.js.map +1 -1
  263. package/dist/plugin/scopeChange.js +22 -0
  264. package/dist/plugin/scopeChange.js.map +1 -0
  265. package/dist/plugin/scopeFieldBoot.js +22 -0
  266. package/dist/plugin/scopeFieldBoot.js.map +1 -0
  267. package/dist/plugin/sourcesEndpoint.js +28 -0
  268. package/dist/plugin/sourcesEndpoint.js.map +1 -0
  269. package/dist/plugin/warmTask.js +0 -0
  270. package/dist/plugin/warmTask.js.map +1 -1
  271. package/dist/providers/access.js +2 -1
  272. package/dist/providers/access.js.map +1 -1
  273. package/dist/providers/collection.js +90 -29
  274. package/dist/providers/collection.js.map +1 -1
  275. package/dist/providers/factory.js +11 -3
  276. package/dist/providers/factory.js.map +1 -1
  277. package/dist/providers/resolver.js.map +1 -1
  278. package/dist/query/dates.js +64 -0
  279. package/dist/query/dates.js.map +1 -0
  280. package/dist/query/errors.d.ts +14 -0
  281. package/dist/query/fetchQuery.d.ts +79 -0
  282. package/dist/query/fetchQuery.js +117 -0
  283. package/dist/query/fetchQuery.js.map +1 -0
  284. package/dist/query/parse.d.ts +22 -0
  285. package/dist/query/parse.js +168 -0
  286. package/dist/query/parse.js.map +1 -0
  287. package/dist/query/response.d.ts +39 -0
  288. package/dist/query/response.js +11 -0
  289. package/dist/query/response.js.map +1 -0
  290. package/dist/react/AnalyticsProvider.d.ts +50 -0
  291. package/dist/react/AnalyticsProvider.js +67 -0
  292. package/dist/react/AnalyticsProvider.js.map +1 -0
  293. package/dist/react/TrackerBoot.d.ts +22 -0
  294. package/dist/react/TrackerBoot.js +30 -0
  295. package/dist/react/TrackerBoot.js.map +1 -0
  296. package/dist/react/useAnalytics.d.ts +20 -0
  297. package/dist/react/useAnalytics.js +52 -0
  298. package/dist/react/useAnalytics.js.map +1 -0
  299. package/dist/rsc/AnalyticsScripts.d.ts +30 -0
  300. package/dist/rsc/AnalyticsScripts.js +41 -0
  301. package/dist/rsc/AnalyticsScripts.js.map +1 -0
  302. package/dist/surfacing/cacheStore.d.ts +1 -0
  303. package/dist/surfacing/cacheStore.js +18 -2
  304. package/dist/surfacing/cacheStore.js.map +1 -1
  305. package/dist/surfacing/engine.d.ts +1 -0
  306. package/dist/surfacing/engine.js +47 -6
  307. package/dist/surfacing/engine.js.map +1 -1
  308. package/dist/surfacing/epoch.d.ts +1 -0
  309. package/dist/surfacing/epoch.js +72 -0
  310. package/dist/surfacing/epoch.js.map +1 -0
  311. package/dist/surfacing/queue.js +22 -6
  312. package/dist/surfacing/queue.js.map +1 -1
  313. package/dist/surfacing/rateLimiter.js +130 -0
  314. package/dist/surfacing/rateLimiter.js.map +1 -0
  315. package/dist/surfacing/retryPolicy.js +15 -0
  316. package/dist/surfacing/retryPolicy.js.map +1 -0
  317. package/dist/sync/collection.js +23 -7
  318. package/dist/sync/collection.js.map +1 -1
  319. package/dist/sync/syncTask.js +68 -33
  320. package/dist/sync/syncTask.js.map +1 -1
  321. package/dist/testing/memoryAdapter.d.ts +2 -0
  322. package/dist/testing/memoryAdapter.js +17 -1
  323. package/dist/testing/memoryAdapter.js.map +1 -1
  324. package/dist/timeframe/tz.js +17 -6
  325. package/dist/timeframe/tz.js.map +1 -1
  326. package/dist/tracker/autoCapture.d.ts +48 -0
  327. package/dist/tracker/autoCapture.js +129 -0
  328. package/dist/tracker/autoCapture.js.map +1 -0
  329. package/dist/tracker/consent.d.ts +24 -0
  330. package/dist/tracker/consent.js +48 -0
  331. package/dist/tracker/consent.js.map +1 -0
  332. package/dist/tracker/createTracker.d.ts +18 -0
  333. package/dist/tracker/createTracker.js +215 -0
  334. package/dist/tracker/createTracker.js.map +1 -0
  335. package/dist/tracker/exclusion.d.ts +28 -0
  336. package/dist/tracker/exclusion.js +50 -0
  337. package/dist/tracker/exclusion.js.map +1 -0
  338. package/dist/tracker/initTracker.d.ts +22 -0
  339. package/dist/tracker/initTracker.js +33 -0
  340. package/dist/tracker/initTracker.js.map +1 -0
  341. package/dist/tracker/loadScript.d.ts +14 -0
  342. package/dist/tracker/loadScript.js +41 -0
  343. package/dist/tracker/loadScript.js.map +1 -0
  344. package/dist/tracker/pageTracking.d.ts +17 -0
  345. package/dist/tracker/pageTracking.js +38 -0
  346. package/dist/tracker/pageTracking.js.map +1 -0
  347. package/dist/tracker/registry.d.ts +27 -0
  348. package/dist/tracker/registry.js +73 -0
  349. package/dist/tracker/registry.js.map +1 -0
  350. package/dist/tracker/sinks/ga4.d.ts +29 -0
  351. package/dist/tracker/sinks/ga4.js +30 -0
  352. package/dist/tracker/sinks/ga4.js.map +1 -0
  353. package/dist/tracker/sinks/native.d.ts +22 -0
  354. package/dist/tracker/sinks/native.js +56 -0
  355. package/dist/tracker/sinks/native.js.map +1 -0
  356. package/dist/tracker/sinks/plausible.d.ts +20 -0
  357. package/dist/tracker/sinks/plausible.js +32 -0
  358. package/dist/tracker/sinks/plausible.js.map +1 -0
  359. package/dist/tracker/sinks/posthog.d.ts +18 -0
  360. package/dist/tracker/sinks/posthog.js +30 -0
  361. package/dist/tracker/sinks/posthog.js.map +1 -0
  362. package/dist/tracker/sinks/umami.d.ts +18 -0
  363. package/dist/tracker/sinks/umami.js +23 -0
  364. package/dist/tracker/sinks/umami.js.map +1 -0
  365. package/dist/tracker/sinks/vendor.d.ts +14 -0
  366. package/dist/tracker/sinks/vendor.js +81 -0
  367. package/dist/tracker/sinks/vendor.js.map +1 -0
  368. package/dist/tracker/transport.js +28 -0
  369. package/dist/tracker/transport.js.map +1 -0
  370. package/dist/tracker/types.d.ts +91 -0
  371. package/dist/translations/ar.js +221 -0
  372. package/dist/translations/ar.js.map +1 -0
  373. package/dist/translations/de.js +145 -1
  374. package/dist/translations/de.js.map +1 -1
  375. package/dist/translations/en.js +145 -1
  376. package/dist/translations/en.js.map +1 -1
  377. package/dist/translations/es.js +221 -0
  378. package/dist/translations/es.js.map +1 -0
  379. package/dist/translations/fr.js +221 -0
  380. package/dist/translations/fr.js.map +1 -0
  381. package/dist/translations/id.js +221 -0
  382. package/dist/translations/id.js.map +1 -0
  383. package/dist/translations/index.d.ts +10 -1
  384. package/dist/translations/index.js +19 -1
  385. package/dist/translations/index.js.map +1 -1
  386. package/dist/translations/keys.d.ts +144 -0
  387. package/dist/translations/keys.js +145 -1
  388. package/dist/translations/keys.js.map +1 -1
  389. package/dist/translations/ko.js +221 -0
  390. package/dist/translations/ko.js.map +1 -0
  391. package/dist/translations/metricKeys.js +8 -2
  392. package/dist/translations/metricKeys.js.map +1 -1
  393. package/dist/translations/pt.js +221 -0
  394. package/dist/translations/pt.js.map +1 -0
  395. package/dist/translations/ru.js +221 -0
  396. package/dist/translations/ru.js.map +1 -0
  397. package/dist/translations/server.js.map +1 -1
  398. package/dist/translations/uk.js +221 -0
  399. package/dist/translations/uk.js.map +1 -0
  400. package/dist/translations/zh.js +221 -0
  401. package/dist/translations/zh.js.map +1 -0
  402. package/dist/view/AnalyticsNavLink.d.ts +19 -0
  403. package/dist/view/AnalyticsNavLink.js +40 -0
  404. package/dist/view/AnalyticsNavLink.js.map +1 -0
  405. package/dist/view/AnalyticsView.d.ts +23 -0
  406. package/dist/view/AnalyticsView.js +45 -0
  407. package/dist/view/AnalyticsView.js.map +1 -0
  408. package/dist/view/AnalyticsViewClient.d.ts +15 -0
  409. package/dist/view/AnalyticsViewClient.js +244 -0
  410. package/dist/view/AnalyticsViewClient.js.map +1 -0
  411. package/dist/view/authRedirect.js +32 -0
  412. package/dist/view/authRedirect.js.map +1 -0
  413. package/dist/view/conversionRate.js +18 -0
  414. package/dist/view/conversionRate.js.map +1 -0
  415. package/dist/view/dayRange.js +68 -0
  416. package/dist/view/dayRange.js.map +1 -0
  417. package/dist/view/gating.d.ts +1 -0
  418. package/dist/view/gating.js +142 -0
  419. package/dist/view/gating.js.map +1 -0
  420. package/dist/view/labels.js +76 -0
  421. package/dist/view/labels.js.map +1 -0
  422. package/dist/view/registerView.js +48 -0
  423. package/dist/view/registerView.js.map +1 -0
  424. package/dist/view/sections/Breakdowns.js +198 -0
  425. package/dist/view/sections/Breakdowns.js.map +1 -0
  426. package/dist/view/sections/EmptyStates.js +92 -0
  427. package/dist/view/sections/EmptyStates.js.map +1 -0
  428. package/dist/view/sections/FilterChips.js +46 -0
  429. package/dist/view/sections/FilterChips.js.map +1 -0
  430. package/dist/view/sections/GoalsPanel.js +82 -0
  431. package/dist/view/sections/GoalsPanel.js.map +1 -0
  432. package/dist/view/sections/OverviewCards.js +65 -0
  433. package/dist/view/sections/OverviewCards.js.map +1 -0
  434. package/dist/view/sections/RealtimeStrip.js +80 -0
  435. package/dist/view/sections/RealtimeStrip.js.map +1 -0
  436. package/dist/view/sections/Toolbar.js +207 -0
  437. package/dist/view/sections/Toolbar.js.map +1 -0
  438. package/dist/view/sections/Trend.js +125 -0
  439. package/dist/view/sections/Trend.js.map +1 -0
  440. package/dist/view/sections/styles.js +76 -0
  441. package/dist/view/sections/styles.js.map +1 -0
  442. package/dist/view/state.js +211 -0
  443. package/dist/view/state.js.map +1 -0
  444. package/dist/view/useViewQueries.js +153 -0
  445. package/dist/view/useViewQueries.js.map +1 -0
  446. package/dist/view/viewProps.d.ts +40 -0
  447. package/dist/view/viewProps.js +90 -0
  448. package/dist/view/viewProps.js.map +1 -0
  449. package/dist/widgets/AnalyticsBreakdownWidget.d.ts +2 -1
  450. package/dist/widgets/AnalyticsBreakdownWidget.js +78 -11
  451. package/dist/widgets/AnalyticsBreakdownWidget.js.map +1 -1
  452. package/dist/widgets/AnalyticsGoalsWidget.d.ts +14 -0
  453. package/dist/widgets/AnalyticsGoalsWidget.js +196 -0
  454. package/dist/widgets/AnalyticsGoalsWidget.js.map +1 -0
  455. package/dist/widgets/AnalyticsMetricWidget.d.ts +2 -1
  456. package/dist/widgets/AnalyticsMetricWidget.js +63 -13
  457. package/dist/widgets/AnalyticsMetricWidget.js.map +1 -1
  458. package/dist/widgets/AnalyticsRealtimeWidget.d.ts +2 -1
  459. package/dist/widgets/AnalyticsRealtimeWidget.js +45 -23
  460. package/dist/widgets/AnalyticsRealtimeWidget.js.map +1 -1
  461. package/dist/widgets/AnalyticsTrendWidget.d.ts +2 -1
  462. package/dist/widgets/AnalyticsTrendWidget.js +79 -16
  463. package/dist/widgets/AnalyticsTrendWidget.js.map +1 -1
  464. package/dist/widgets/RealtimeCounter.d.ts +4 -0
  465. package/dist/widgets/RealtimeCounter.js +18 -4
  466. package/dist/widgets/RealtimeCounter.js.map +1 -1
  467. package/dist/widgets/WidgetViewLink.js +17 -0
  468. package/dist/widgets/WidgetViewLink.js.map +1 -0
  469. package/dist/widgets/breakdownTypes.js +38 -0
  470. package/dist/widgets/breakdownTypes.js.map +1 -1
  471. package/dist/widgets/cardChrome.js +31 -7
  472. package/dist/widgets/cardChrome.js.map +1 -1
  473. package/dist/widgets/comparison.js +15 -1
  474. package/dist/widgets/comparison.js.map +1 -1
  475. package/dist/widgets/defaults.d.ts +6 -2
  476. package/dist/widgets/defaults.js +78 -23
  477. package/dist/widgets/defaults.js.map +1 -1
  478. package/dist/widgets/filterCaption.js +27 -0
  479. package/dist/widgets/filterCaption.js.map +1 -0
  480. package/dist/widgets/filterField.d.ts +19 -0
  481. package/dist/widgets/filterField.js +75 -0
  482. package/dist/widgets/filterField.js.map +1 -0
  483. package/dist/widgets/prepareWidgetRead.d.ts +7 -0
  484. package/dist/widgets/prepareWidgetRead.js +74 -0
  485. package/dist/widgets/prepareWidgetRead.js.map +1 -0
  486. package/dist/widgets/range.js +43 -12
  487. package/dist/widgets/range.js.map +1 -1
  488. package/dist/widgets/readForWidget.d.ts +26 -3
  489. package/dist/widgets/readForWidget.js +48 -44
  490. package/dist/widgets/readForWidget.js.map +1 -1
  491. package/dist/widgets/readForWidgetBreakdown.d.ts +34 -2
  492. package/dist/widgets/readForWidgetBreakdown.js +53 -49
  493. package/dist/widgets/readForWidgetBreakdown.js.map +1 -1
  494. package/dist/widgets/readForWidgetGoals.d.ts +67 -0
  495. package/dist/widgets/readForWidgetGoals.js +140 -0
  496. package/dist/widgets/readForWidgetGoals.js.map +1 -0
  497. package/dist/widgets/readForWidgetRealtime.d.ts +8 -0
  498. package/dist/widgets/readForWidgetRealtime.js +23 -21
  499. package/dist/widgets/readForWidgetRealtime.js.map +1 -1
  500. package/dist/widgets/readForWidgetSeries.d.ts +26 -2
  501. package/dist/widgets/readForWidgetSeries.js +78 -53
  502. package/dist/widgets/readForWidgetSeries.js.map +1 -1
  503. package/dist/widgets/readMeta.js +18 -0
  504. package/dist/widgets/readMeta.js.map +1 -0
  505. package/dist/widgets/realtimePoll.js +16 -1
  506. package/dist/widgets/realtimePoll.js.map +1 -1
  507. package/dist/widgets/registerWidgets.js +76 -14
  508. package/dist/widgets/registerWidgets.js.map +1 -1
  509. package/dist/widgets/types.d.ts +15 -0
  510. package/dist/widgets/types.js +16 -2
  511. package/dist/widgets/types.js.map +1 -1
  512. package/dist/widgets/viewLink.d.ts +22 -0
  513. package/dist/widgets/viewLink.js +86 -0
  514. package/dist/widgets/viewLink.js.map +1 -0
  515. package/package.json +27 -7
  516. package/dist/native/rollups/applyDistinctDeltas.js +0 -9
  517. package/dist/native/rollups/applyDistinctDeltas.js.map +0 -1
  518. package/dist/native/rollups/bumpRollup.js +0 -68
  519. package/dist/native/rollups/bumpRollup.js.map +0 -1
  520. package/dist/native/rollups/insertIfNew.js +0 -19
  521. package/dist/native/rollups/insertIfNew.js.map +0 -1
@@ -0,0 +1,30 @@
1
+ //#region src/native/ingest/normalizeEvent.d.ts
2
+ type EventType = 'pageview' | 'event' | 'goal';
3
+ interface RawEventInput {
4
+ type: EventType;
5
+ /** Event name, or the goal slug on a `goal`. Absent on pageviews. */
6
+ name?: string;
7
+ path: string;
8
+ /**
9
+ * The hostname the client claims. Ignored by the HTTP ingest, which attributes an event to
10
+ * the request that carried it; `trackServerEvent` supplies its own and it is used as sent.
11
+ */
12
+ hostname?: string;
13
+ referrer?: string;
14
+ /**
15
+ * The page's query string, without its leading `?`. Read for its utm keys and then
16
+ * discarded: it is never stored, so a session token or an email address that happens to
17
+ * be in the URL never lands in the events collection.
18
+ */
19
+ query?: string;
20
+ durationMs?: number;
21
+ props?: Record<string, unknown>;
22
+ /** Revenue for a goal completion, in `currency`. */
23
+ value?: number;
24
+ currency?: string;
25
+ /** Max scroll depth reached on a pageview, 0-100. */
26
+ scrollDepth?: number;
27
+ }
28
+ //#endregion
29
+ export { RawEventInput };
30
+ //# sourceMappingURL=normalizeEvent.d.ts.map
@@ -1,34 +1,133 @@
1
+ import { clientIpFromHeaders } from "./clientIp.js";
1
2
  import { classifyDevice } from "./device.js";
2
- import { deriveSource } from "./source.js";
3
+ import { matchGoals } from "../../goals/match.js";
4
+ import { classifyBrowser, classifyOs } from "./browser.js";
5
+ import { primaryLanguage } from "./language.js";
6
+ import { referrerHost, storedReferrer } from "./referrer.js";
7
+ import { extractUtm } from "./utm.js";
8
+ import { classifyChannel, deriveSource } from "./source.js";
3
9
  import { dailyVisitorHash, deriveSessionId } from "./visitorHash.js";
4
10
  //#region src/native/ingest/normalizeEvent.ts
5
- async function normalizeEvent({ raw, headers, geoResolver, salt, now, scope, timezone }) {
6
- const geo = await geoResolver(headers);
7
- const ip = (headers.get("x-forwarded-for")?.split(",")[0] ?? headers.get("x-real-ip") ?? "").trim();
11
+ const MAX_PROPS = 20;
12
+ const MAX_KEY_LENGTH = 64;
13
+ const MAX_VALUE_LENGTH = 256;
14
+ const MAX_NAME_LENGTH = 128;
15
+ const MAX_PATH_LENGTH = 512;
16
+ /** 24 hours. A longer duration is a broken clock, not a session. */
17
+ const MAX_DURATION_MS = 864e5;
18
+ const CURRENCY = /^[A-Z]{3}$/;
19
+ /**
20
+ * Optional wire fields are sanitized rather than rejected: a bad `value`, `currency`,
21
+ * `scrollDepth`, `durationMs`, or prop is dropped and the event is still ingested, so one malformed
22
+ * attribute never costs a pageview. Only the required fields (checked in the endpoint)
23
+ * can fail an event.
24
+ */
25
+ const nonNegative = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : void 0;
26
+ const currencyCode = (value) => typeof value === "string" && CURRENCY.test(value) ? value : void 0;
27
+ /**
28
+ * Infinity would poison a rollup bucket's average for good, and a string would throw out of
29
+ * the write and take the whole buffered batch with it, so a duration outside the ceiling is
30
+ * dropped like any other malformed attribute.
31
+ */
32
+ const duration = (value) => {
33
+ const n = nonNegative(value);
34
+ return n === void 0 || n > MAX_DURATION_MS ? void 0 : n;
35
+ };
36
+ /** The event name is a rollup bucket key (the `event` dimension), so it is length-capped. */
37
+ const eventName = (value) => typeof value === "string" ? value.slice(0, MAX_NAME_LENGTH) : void 0;
38
+ /**
39
+ * A geo value as stored. The resolver reads request headers a client can set, and each value
40
+ * becomes a rollup dimvalue and part of a seen-ledger key, so it is capped here rather than
41
+ * trusted. An empty value stays absent: '' would be a bucket of its own.
42
+ */
43
+ const geoValue = (value) => value ? value.slice(0, 128) : void 0;
44
+ /** Capped before it is parsed, so a hostile query cannot make ingest do unbounded work. */
45
+ const queryString = (value) => typeof value === "string" ? value.slice(0, 512) : void 0;
46
+ const depth = (value) => {
47
+ const n = nonNegative(value);
48
+ return n === void 0 ? void 0 : Math.round(Math.min(n, 100));
49
+ };
50
+ /** Flat JSON scalars only: the first 20 short-keyed string/number/boolean entries. */
51
+ const sanitizeProps = (raw) => {
52
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return;
53
+ const out = {};
54
+ let kept = 0;
55
+ for (const [key, value] of Object.entries(raw)) {
56
+ if (kept >= MAX_PROPS || key.length > MAX_KEY_LENGTH) continue;
57
+ if (typeof value === "string") out[key] = value.slice(0, MAX_VALUE_LENGTH);
58
+ else if (typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) out[key] = value;
59
+ else continue;
60
+ kept++;
61
+ }
62
+ return kept > 0 ? out : void 0;
63
+ };
64
+ async function normalizeEvent({ raw, hostname: rawHostname, headers, geoResolver, salt, now, scope, timezone, goals, trustedProxyHops }) {
65
+ const geo = await geoResolver(headers, { trustedProxyHops });
66
+ const ip = clientIpFromHeaders(headers, { trustedProxyHops }) ?? "";
8
67
  const ua = headers.get("user-agent") ?? "";
68
+ const path = raw.path.slice(0, MAX_PATH_LENGTH);
69
+ const hostname = rawHostname.slice(0, 253);
9
70
  const visitorHash = dailyVisitorHash({
10
71
  ip,
11
72
  ua,
12
- site: raw.hostname,
73
+ site: hostname,
13
74
  salt
14
75
  });
15
76
  const hourBucket = now.toISOString().slice(0, 13);
77
+ const props = sanitizeProps(raw.props);
78
+ const value = nonNegative(raw.value);
79
+ const scrollDepth = depth(raw.scrollDepth);
80
+ const durationMs = duration(raw.durationMs);
81
+ const name = eventName(raw.name);
82
+ const device = classifyDevice(ua);
83
+ const browser = classifyBrowser(ua);
84
+ const os = classifyOs(ua);
85
+ const language = primaryLanguage(headers.get("accept-language"));
86
+ const refHost = referrerHost(raw.referrer, hostname);
87
+ const query = queryString(raw.query);
88
+ const utm = extractUtm(query);
89
+ const completions = goals?.length ? matchGoals({
90
+ type: raw.type,
91
+ name,
92
+ path,
93
+ props,
94
+ value
95
+ }, goals) : [];
16
96
  return {
17
97
  timestamp: now,
18
98
  type: raw.type,
19
- name: raw.name,
20
- path: raw.path,
21
- hostname: raw.hostname,
22
- referrer: raw.referrer,
23
- device: classifyDevice(ua),
24
- source: deriveSource(raw.referrer, raw.hostname),
25
- country: geo.country,
26
- region: geo.region,
27
- city: geo.city,
99
+ name,
100
+ path,
101
+ hostname,
102
+ referrer: storedReferrer(raw.referrer),
103
+ ...refHost ? { referrerHost: refHost } : {},
104
+ ...device ? { device } : {},
105
+ ...browser ? { browser } : {},
106
+ ...os ? { os } : {},
107
+ source: deriveSource({
108
+ referrerHost: refHost,
109
+ utmSource: utm.utmSource
110
+ }),
111
+ channel: classifyChannel({
112
+ referrerHost: refHost,
113
+ utmSource: utm.utmSource,
114
+ utmMedium: utm.utmMedium,
115
+ query
116
+ }),
117
+ channelVersion: 1,
118
+ ...utm,
119
+ country: geoValue(geo.country),
120
+ region: geoValue(geo.region),
121
+ city: geoValue(geo.city),
122
+ ...language ? { language } : {},
28
123
  visitorHash,
29
124
  sessionId: deriveSessionId(visitorHash, hourBucket),
30
- durationMs: raw.durationMs,
31
- props: raw.props,
125
+ props,
126
+ ...durationMs !== void 0 ? { durationMs } : {},
127
+ ...value !== void 0 ? { value } : {},
128
+ ...currencyCode(raw.currency) !== void 0 ? { currency: raw.currency } : {},
129
+ ...scrollDepth !== void 0 ? { scrollDepth } : {},
130
+ ...completions.length > 0 ? { goals: completions } : {},
32
131
  ...scope !== void 0 ? { scope } : {},
33
132
  ...timezone !== void 0 ? { timezone } : {}
34
133
  };
@@ -1 +1 @@
1
- {"version":3,"file":"normalizeEvent.js","names":[],"sources":["../../../src/native/ingest/normalizeEvent.ts"],"sourcesContent":["import type { GeoResolver } from '../geo/geoResolver'\nimport { classifyDevice, type DeviceType } from './device'\nimport { deriveSource } from './source'\nimport { dailyVisitorHash, deriveSessionId } from './visitorHash'\n\nexport interface RawEventInput {\n\ttype: 'pageview' | 'event'\n\tname?: string\n\tpath: string\n\thostname: string\n\treferrer?: string\n\tdurationMs?: number\n\tprops?: Record<string, unknown>\n}\n\nexport interface StoredEvent {\n\ttimestamp: Date\n\ttype: 'pageview' | 'event'\n\tname?: string\n\tpath: string\n\thostname: string\n\treferrer?: string\n\tdevice?: DeviceType\n\tsource?: string\n\tcountry?: string\n\tregion?: string\n\tcity?: string\n\tvisitorHash: string\n\tsessionId: string\n\tdurationMs?: number\n\tprops?: Record<string, unknown>\n\t/** Set only in scoped installs; '' is the null scope. */\n\tscope?: string\n\t/**\n\t * Reporting timezone the rollup day bucket is computed in. In-memory only: stripped\n\t * before the event row is persisted (day bucketing happens at rollup time). Absent\n\t * means UTC.\n\t */\n\ttimezone?: string\n}\n\nexport interface NormalizeArgs {\n\traw: RawEventInput\n\theaders: Headers\n\tgeoResolver: GeoResolver\n\tsalt: string\n\tnow: Date\n\tscope?: string\n\ttimezone?: string\n}\n\nexport async function normalizeEvent({\n\traw,\n\theaders,\n\tgeoResolver,\n\tsalt,\n\tnow,\n\tscope,\n\ttimezone,\n}: NormalizeArgs): Promise<StoredEvent> {\n\tconst geo = await geoResolver(headers)\n\tconst ip = (\n\t\theaders.get('x-forwarded-for')?.split(',')[0] ??\n\t\theaders.get('x-real-ip') ??\n\t\t''\n\t).trim()\n\tconst ua = headers.get('user-agent') ?? ''\n\tconst visitorHash = dailyVisitorHash({ ip, ua, site: raw.hostname, salt })\n\tconst hourBucket = now.toISOString().slice(0, 13)\n\treturn {\n\t\ttimestamp: now,\n\t\ttype: raw.type,\n\t\tname: raw.name,\n\t\tpath: raw.path,\n\t\thostname: raw.hostname,\n\t\treferrer: raw.referrer,\n\t\tdevice: classifyDevice(ua),\n\t\tsource: deriveSource(raw.referrer, raw.hostname),\n\t\tcountry: geo.country,\n\t\tregion: geo.region,\n\t\tcity: geo.city,\n\t\tvisitorHash,\n\t\tsessionId: deriveSessionId(visitorHash, hourBucket),\n\t\tdurationMs: raw.durationMs,\n\t\tprops: raw.props,\n\t\t...(scope !== undefined ? { scope } : {}),\n\t\t...(timezone !== undefined ? { timezone } : {}),\n\t}\n}\n"],"mappings":";;;;AAmDA,eAAsB,eAAe,EACpC,KACA,SACA,aACA,MACA,KACA,OACA,YACuC;CACvC,MAAM,MAAM,MAAM,YAAY,OAAO;CACrC,MAAM,MACL,QAAQ,IAAI,iBAAiB,GAAG,MAAM,GAAG,EAAE,MAC3C,QAAQ,IAAI,WAAW,KACvB,IACC,KAAK;CACP,MAAM,KAAK,QAAQ,IAAI,YAAY,KAAK;CACxC,MAAM,cAAc,iBAAiB;EAAE;EAAI;EAAI,MAAM,IAAI;EAAU;CAAK,CAAC;CACzE,MAAM,aAAa,IAAI,YAAY,EAAE,MAAM,GAAG,EAAE;CAChD,OAAO;EACN,WAAW;EACX,MAAM,IAAI;EACV,MAAM,IAAI;EACV,MAAM,IAAI;EACV,UAAU,IAAI;EACd,UAAU,IAAI;EACd,QAAQ,eAAe,EAAE;EACzB,QAAQ,aAAa,IAAI,UAAU,IAAI,QAAQ;EAC/C,SAAS,IAAI;EACb,QAAQ,IAAI;EACZ,MAAM,IAAI;EACV;EACA,WAAW,gBAAgB,aAAa,UAAU;EAClD,YAAY,IAAI;EAChB,OAAO,IAAI;EACX,GAAI,UAAU,KAAA,IAAY,EAAE,MAAM,IAAI,CAAC;EACvC,GAAI,aAAa,KAAA,IAAY,EAAE,SAAS,IAAI,CAAC;CAC9C;AACD"}
1
+ {"version":3,"file":"normalizeEvent.js","names":[],"sources":["../../../src/native/ingest/normalizeEvent.ts"],"sourcesContent":["import { type GoalCompletion, matchGoals } from '../../goals/match'\nimport type { Goal } from '../../goals/types'\nimport { MAX_GEO_LENGTH, MAX_QUERY_LENGTH, MAX_REFERRER_LENGTH } from '../../query/limits'\nimport type { GeoResolver } from '../geo/geoResolver'\nimport { type BrowserName, classifyBrowser, classifyOs, type OsName } from './browser'\nimport { clientIpFromHeaders } from './clientIp'\nimport { classifyDevice, type DeviceType } from './device'\nimport { primaryLanguage } from './language'\nimport { referrerHost, storedReferrer } from './referrer'\nimport { MAX_HOSTNAME_LENGTH } from './requestHost'\nimport { CHANNEL_TAXONOMY_VERSION, classifyChannel, deriveSource } from './source'\nimport { extractUtm } from './utm'\nimport { dailyVisitorHash, deriveSessionId } from './visitorHash'\n\n/** The wire caps, re-exported beside the sanitizers that apply them. */\nexport { MAX_GEO_LENGTH, MAX_QUERY_LENGTH, MAX_REFERRER_LENGTH }\n\nexport type EventType = 'pageview' | 'event' | 'goal'\n\nexport interface RawEventInput {\n\ttype: EventType\n\t/** Event name, or the goal slug on a `goal`. Absent on pageviews. */\n\tname?: string\n\tpath: string\n\t/**\n\t * The hostname the client claims. Ignored by the HTTP ingest, which attributes an event to\n\t * the request that carried it; `trackServerEvent` supplies its own and it is used as sent.\n\t */\n\thostname?: string\n\treferrer?: string\n\t/**\n\t * The page's query string, without its leading `?`. Read for its utm keys and then\n\t * discarded: it is never stored, so a session token or an email address that happens to\n\t * be in the URL never lands in the events collection.\n\t */\n\tquery?: string\n\tdurationMs?: number\n\tprops?: Record<string, unknown>\n\t/** Revenue for a goal completion, in `currency`. */\n\tvalue?: number\n\tcurrency?: string\n\t/** Max scroll depth reached on a pageview, 0-100. */\n\tscrollDepth?: number\n}\n\nexport interface StoredEvent {\n\ttimestamp: Date\n\ttype: EventType\n\tname?: string\n\tpath: string\n\thostname: string\n\t/** Origin and path only: the query string and fragment are stripped before storage. */\n\treferrer?: string\n\t/**\n\t * The referrer's bare host, derived at ingest because a `where` cannot derive it at read\n\t * time: it is what the `referrer` dimension buckets and filters on.\n\t */\n\treferrerHost?: string\n\tdevice?: DeviceType\n\tbrowser?: BrowserName\n\tos?: OsName\n\t/**\n\t * The visit's named origin: its `utm_source`, else the referrer host, else `direct`.\n\t * Typed as a string because a row written before this classification holds whatever the\n\t * rules of its day decided, and rows are never rewritten.\n\t */\n\tsource?: string\n\t/** The hit's acquisition channel (`TrafficChannel`), classified from the origin above. */\n\tchannel: string\n\t/**\n\t * The taxonomy the `channel` beside it was decided under, so a later reclassify can find\n\t * the rows an older rule set wrote.\n\t */\n\tchannelVersion: number\n\t/** The five campaign keys extracted from the wire `query`; absent when it carried none. */\n\tutmSource?: string\n\tutmMedium?: string\n\tutmCampaign?: string\n\tutmContent?: string\n\tutmTerm?: string\n\tcountry?: string\n\tregion?: string\n\tcity?: string\n\t/** Primary `Accept-Language` tag, lowercased (`de-de`). */\n\tlanguage?: string\n\tvisitorHash: string\n\tsessionId: string\n\tdurationMs?: number\n\tprops?: Record<string, unknown>\n\tvalue?: number\n\t/** ISO 4217 code `value` is denominated in. Stored as sent; revenue is never converted. */\n\tcurrency?: string\n\tscrollDepth?: number\n\t/**\n\t * Goals this event completed, resolved against the install's goals at ingest so a later\n\t * goal edit never rewrites history and a raw-event read can re-derive the same numbers\n\t * the rollups hold.\n\t */\n\tgoals?: GoalCompletion[]\n\t/** Set only in scoped installs; '' is the null scope. */\n\tscope?: string\n\t/**\n\t * Reporting timezone the rollup day bucket is computed in. In-memory only: stripped\n\t * before the event row is persisted (day bucketing happens at rollup time). Absent\n\t * means UTC.\n\t */\n\ttimezone?: string\n}\n\nexport interface NormalizeArgs {\n\traw: RawEventInput\n\t/** Already resolved and capped: what the event is attributed to, not what it claimed. */\n\thostname: string\n\theaders: Headers\n\tgeoResolver: GeoResolver\n\tsalt: string\n\tnow: Date\n\tscope?: string\n\ttimezone?: string\n\t/** Goals to match this event against; omitted means no goal matching. */\n\tgoals?: Goal[]\n\t/** Trusted proxies in front of the app, for the client address the hash and geo read. */\n\ttrustedProxyHops?: number\n}\n\nconst MAX_PROPS = 20\nconst MAX_KEY_LENGTH = 64\nconst MAX_VALUE_LENGTH = 256\nconst MAX_NAME_LENGTH = 128\nconst MAX_PATH_LENGTH = 512\n/** 24 hours. A longer duration is a broken clock, not a session. */\nconst MAX_DURATION_MS = 86_400_000\nconst CURRENCY = /^[A-Z]{3}$/\n\n/**\n * Optional wire fields are sanitized rather than rejected: a bad `value`, `currency`,\n * `scrollDepth`, `durationMs`, or prop is dropped and the event is still ingested, so one malformed\n * attribute never costs a pageview. Only the required fields (checked in the endpoint)\n * can fail an event.\n */\nconst nonNegative = (value: unknown): number | undefined =>\n\ttypeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined\n\nconst currencyCode = (value: unknown): string | undefined =>\n\ttypeof value === 'string' && CURRENCY.test(value) ? value : undefined\n\n/**\n * Infinity would poison a rollup bucket's average for good, and a string would throw out of\n * the write and take the whole buffered batch with it, so a duration outside the ceiling is\n * dropped like any other malformed attribute.\n */\nconst duration = (value: unknown): number | undefined => {\n\tconst n = nonNegative(value)\n\treturn n === undefined || n > MAX_DURATION_MS ? undefined : n\n}\n\n/** The event name is a rollup bucket key (the `event` dimension), so it is length-capped. */\nconst eventName = (value: unknown): string | undefined =>\n\ttypeof value === 'string' ? value.slice(0, MAX_NAME_LENGTH) : undefined\n\n/**\n * A geo value as stored. The resolver reads request headers a client can set, and each value\n * becomes a rollup dimvalue and part of a seen-ledger key, so it is capped here rather than\n * trusted. An empty value stays absent: '' would be a bucket of its own.\n */\nconst geoValue = (value: string | undefined): string | undefined =>\n\tvalue ? value.slice(0, MAX_GEO_LENGTH) : undefined\n\n/** Capped before it is parsed, so a hostile query cannot make ingest do unbounded work. */\nconst queryString = (value: unknown): string | undefined =>\n\ttypeof value === 'string' ? value.slice(0, MAX_QUERY_LENGTH) : undefined\n\nconst depth = (value: unknown): number | undefined => {\n\tconst n = nonNegative(value)\n\treturn n === undefined ? undefined : Math.round(Math.min(n, 100))\n}\n\n/** Flat JSON scalars only: the first 20 short-keyed string/number/boolean entries. */\nconst sanitizeProps = (raw: unknown): Record<string, unknown> | undefined => {\n\tif (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {\n\t\treturn undefined\n\t}\n\tconst out: Record<string, unknown> = {}\n\tlet kept = 0\n\tfor (const [key, value] of Object.entries(raw)) {\n\t\tif (kept >= MAX_PROPS || key.length > MAX_KEY_LENGTH) {\n\t\t\tcontinue\n\t\t}\n\t\tif (typeof value === 'string') {\n\t\t\tout[key] = value.slice(0, MAX_VALUE_LENGTH)\n\t\t} else if (\n\t\t\ttypeof value === 'boolean' ||\n\t\t\t(typeof value === 'number' && Number.isFinite(value))\n\t\t) {\n\t\t\tout[key] = value\n\t\t} else {\n\t\t\tcontinue\n\t\t}\n\t\tkept++\n\t}\n\treturn kept > 0 ? out : undefined\n}\n\nexport async function normalizeEvent({\n\traw,\n\thostname: rawHostname,\n\theaders,\n\tgeoResolver,\n\tsalt,\n\tnow,\n\tscope,\n\ttimezone,\n\tgoals,\n\ttrustedProxyHops,\n}: NormalizeArgs): Promise<StoredEvent> {\n\tconst geo = await geoResolver(headers, { trustedProxyHops })\n\tconst ip = clientIpFromHeaders(headers, { trustedProxyHops }) ?? ''\n\tconst ua = headers.get('user-agent') ?? ''\n\t// Everything that becomes a rollup dimvalue or a seen-ledger key is capped before anything\n\t// derives from it: an uncapped value exceeds Mongo's index key limit, and on Postgres a\n\t// btree key over 2704 bytes fails the write outright. That covers path and hostname here,\n\t// the geo values below (a client can set the headers a resolver reads), and the event name,\n\t// query and referrer in their own sanitizers.\n\tconst path = raw.path.slice(0, MAX_PATH_LENGTH)\n\tconst hostname = rawHostname.slice(0, MAX_HOSTNAME_LENGTH)\n\tconst visitorHash = dailyVisitorHash({ ip, ua, site: hostname, salt })\n\tconst hourBucket = now.toISOString().slice(0, 13)\n\tconst props = sanitizeProps(raw.props)\n\tconst value = nonNegative(raw.value)\n\tconst scrollDepth = depth(raw.scrollDepth)\n\tconst durationMs = duration(raw.durationMs)\n\tconst name = eventName(raw.name)\n\tconst device = classifyDevice(ua)\n\tconst browser = classifyBrowser(ua)\n\tconst os = classifyOs(ua)\n\tconst language = primaryLanguage(headers.get('accept-language'))\n\tconst refHost = referrerHost(raw.referrer, hostname)\n\tconst query = queryString(raw.query)\n\tconst utm = extractUtm(query)\n\t// Match on the sanitized fields so a rejected value never reaches a goal's revenue.\n\tconst completions = goals?.length\n\t\t? matchGoals({ type: raw.type, name, path, props, value }, goals)\n\t\t: []\n\treturn {\n\t\ttimestamp: now,\n\t\ttype: raw.type,\n\t\tname,\n\t\tpath,\n\t\thostname,\n\t\treferrer: storedReferrer(raw.referrer),\n\t\t...(refHost ? { referrerHost: refHost } : {}),\n\t\t...(device ? { device } : {}),\n\t\t...(browser ? { browser } : {}),\n\t\t...(os ? { os } : {}),\n\t\tsource: deriveSource({ referrerHost: refHost, utmSource: utm.utmSource }),\n\t\tchannel: classifyChannel({\n\t\t\treferrerHost: refHost,\n\t\t\tutmSource: utm.utmSource,\n\t\t\tutmMedium: utm.utmMedium,\n\t\t\tquery,\n\t\t}),\n\t\tchannelVersion: CHANNEL_TAXONOMY_VERSION,\n\t\t...utm,\n\t\tcountry: geoValue(geo.country),\n\t\tregion: geoValue(geo.region),\n\t\tcity: geoValue(geo.city),\n\t\t...(language ? { language } : {}),\n\t\tvisitorHash,\n\t\tsessionId: deriveSessionId(visitorHash, hourBucket),\n\t\tprops,\n\t\t...(durationMs !== undefined ? { durationMs } : {}),\n\t\t...(value !== undefined ? { value } : {}),\n\t\t...(currencyCode(raw.currency) !== undefined ? { currency: raw.currency } : {}),\n\t\t...(scrollDepth !== undefined ? { scrollDepth } : {}),\n\t\t...(completions.length > 0 ? { goals: completions } : {}),\n\t\t...(scope !== undefined ? { scope } : {}),\n\t\t...(timezone !== undefined ? { timezone } : {}),\n\t}\n}\n"],"mappings":";;;;;;;;;;AA6HA,MAAM,YAAY;AAClB,MAAM,iBAAiB;AACvB,MAAM,mBAAmB;AACzB,MAAM,kBAAkB;AACxB,MAAM,kBAAkB;;AAExB,MAAM,kBAAkB;AACxB,MAAM,WAAW;;;;;;;AAQjB,MAAM,eAAe,UACpB,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK,KAAK,SAAS,IAAI,QAAQ,KAAA;AAE7E,MAAM,gBAAgB,UACrB,OAAO,UAAU,YAAY,SAAS,KAAK,KAAK,IAAI,QAAQ,KAAA;;;;;;AAO7D,MAAM,YAAY,UAAuC;CACxD,MAAM,IAAI,YAAY,KAAK;CAC3B,OAAO,MAAM,KAAA,KAAa,IAAI,kBAAkB,KAAA,IAAY;AAC7D;;AAGA,MAAM,aAAa,UAClB,OAAO,UAAU,WAAW,MAAM,MAAM,GAAG,eAAe,IAAI,KAAA;;;;;;AAO/D,MAAM,YAAY,UACjB,QAAQ,MAAM,MAAM,GAAA,GAAiB,IAAI,KAAA;;AAG1C,MAAM,eAAe,UACpB,OAAO,UAAU,WAAW,MAAM,MAAM,GAAA,GAAmB,IAAI,KAAA;AAEhE,MAAM,SAAS,UAAuC;CACrD,MAAM,IAAI,YAAY,KAAK;CAC3B,OAAO,MAAM,KAAA,IAAY,KAAA,IAAY,KAAK,MAAM,KAAK,IAAI,GAAG,GAAG,CAAC;AACjE;;AAGA,MAAM,iBAAiB,QAAsD;CAC5E,IAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,MAAM,QAAQ,GAAG,GAC/D;CAED,MAAM,MAA+B,CAAC;CACtC,IAAI,OAAO;CACX,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,GAAG,GAAG;EAC/C,IAAI,QAAQ,aAAa,IAAI,SAAS,gBACrC;EAED,IAAI,OAAO,UAAU,UACpB,IAAI,OAAO,MAAM,MAAM,GAAG,gBAAgB;OACpC,IACN,OAAO,UAAU,aAChB,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK,GAEnD,IAAI,OAAO;OAEX;EAED;CACD;CACA,OAAO,OAAO,IAAI,MAAM,KAAA;AACzB;AAEA,eAAsB,eAAe,EACpC,KACA,UAAU,aACV,SACA,aACA,MACA,KACA,OACA,UACA,OACA,oBACuC;CACvC,MAAM,MAAM,MAAM,YAAY,SAAS,EAAE,iBAAiB,CAAC;CAC3D,MAAM,KAAK,oBAAoB,SAAS,EAAE,iBAAiB,CAAC,KAAK;CACjE,MAAM,KAAK,QAAQ,IAAI,YAAY,KAAK;CAMxC,MAAM,OAAO,IAAI,KAAK,MAAM,GAAG,eAAe;CAC9C,MAAM,WAAW,YAAY,MAAM,GAAA,GAAsB;CACzD,MAAM,cAAc,iBAAiB;EAAE;EAAI;EAAI,MAAM;EAAU;CAAK,CAAC;CACrE,MAAM,aAAa,IAAI,YAAY,EAAE,MAAM,GAAG,EAAE;CAChD,MAAM,QAAQ,cAAc,IAAI,KAAK;CACrC,MAAM,QAAQ,YAAY,IAAI,KAAK;CACnC,MAAM,cAAc,MAAM,IAAI,WAAW;CACzC,MAAM,aAAa,SAAS,IAAI,UAAU;CAC1C,MAAM,OAAO,UAAU,IAAI,IAAI;CAC/B,MAAM,SAAS,eAAe,EAAE;CAChC,MAAM,UAAU,gBAAgB,EAAE;CAClC,MAAM,KAAK,WAAW,EAAE;CACxB,MAAM,WAAW,gBAAgB,QAAQ,IAAI,iBAAiB,CAAC;CAC/D,MAAM,UAAU,aAAa,IAAI,UAAU,QAAQ;CACnD,MAAM,QAAQ,YAAY,IAAI,KAAK;CACnC,MAAM,MAAM,WAAW,KAAK;CAE5B,MAAM,cAAc,OAAO,SACxB,WAAW;EAAE,MAAM,IAAI;EAAM;EAAM;EAAM;EAAO;CAAM,GAAG,KAAK,IAC9D,CAAC;CACJ,OAAO;EACN,WAAW;EACX,MAAM,IAAI;EACV;EACA;EACA;EACA,UAAU,eAAe,IAAI,QAAQ;EACrC,GAAI,UAAU,EAAE,cAAc,QAAQ,IAAI,CAAC;EAC3C,GAAI,SAAS,EAAE,OAAO,IAAI,CAAC;EAC3B,GAAI,UAAU,EAAE,QAAQ,IAAI,CAAC;EAC7B,GAAI,KAAK,EAAE,GAAG,IAAI,CAAC;EACnB,QAAQ,aAAa;GAAE,cAAc;GAAS,WAAW,IAAI;EAAU,CAAC;EACxE,SAAS,gBAAgB;GACxB,cAAc;GACd,WAAW,IAAI;GACf,WAAW,IAAI;GACf;EACD,CAAC;EACD,gBAAA;EACA,GAAG;EACH,SAAS,SAAS,IAAI,OAAO;EAC7B,QAAQ,SAAS,IAAI,MAAM;EAC3B,MAAM,SAAS,IAAI,IAAI;EACvB,GAAI,WAAW,EAAE,SAAS,IAAI,CAAC;EAC/B;EACA,WAAW,gBAAgB,aAAa,UAAU;EAClD;EACA,GAAI,eAAe,KAAA,IAAY,EAAE,WAAW,IAAI,CAAC;EACjD,GAAI,UAAU,KAAA,IAAY,EAAE,MAAM,IAAI,CAAC;EACvC,GAAI,aAAa,IAAI,QAAQ,MAAM,KAAA,IAAY,EAAE,UAAU,IAAI,SAAS,IAAI,CAAC;EAC7E,GAAI,gBAAgB,KAAA,IAAY,EAAE,YAAY,IAAI,CAAC;EACnD,GAAI,YAAY,SAAS,IAAI,EAAE,OAAO,YAAY,IAAI,CAAC;EACvD,GAAI,UAAU,KAAA,IAAY,EAAE,MAAM,IAAI,CAAC;EACvC,GAAI,aAAa,KAAA,IAAY,EAAE,SAAS,IAAI,CAAC;CAC9C;AACD"}
@@ -0,0 +1,48 @@
1
+ //#region src/native/ingest/referrer.ts
2
+ /** A hostname as it is compared: lowercased, without a leading `www.`. */
3
+ const bareHost = (host) => host.toLowerCase().replace(/^www\./, "");
4
+ /**
5
+ * The referrer as it is stored: everything from the first `#` or `?` onwards removed, then
6
+ * capped. A same-origin navigation puts the previous page's whole URL in `document.referrer`,
7
+ * so the query string routinely carries a reset token, a session id or an email address that
8
+ * has no business in an analytics row. Origin and path are kept verbatim, case included,
9
+ * because they are what makes a referrer readable. The fragment goes first: a `?` after a
10
+ * `#` belongs to the fragment, not to a query.
11
+ *
12
+ * An unparseable referrer is stripped on the same terms rather than trusted, and a value that
13
+ * is not a string at all is dropped: the wire field is public and unvalidated, so a body
14
+ * carrying `"referrer": {}` must cost the event its referrer, not the request its response.
15
+ */
16
+ const storedReferrer = (raw) => {
17
+ if (typeof raw !== "string") return;
18
+ const stripped = raw.split("#")[0]?.split("?")[0];
19
+ return stripped ? stripped.slice(0, 512) : void 0;
20
+ };
21
+ /**
22
+ * The referrer's bare host, which is what the `referrer` dimension buckets and reads by:
23
+ * lowercased, without scheme, port, path, query or a leading `www.`. Nothing is reported for
24
+ * a missing, non-string, hostless or unparseable referrer, so the event contributes no
25
+ * referrer bucket.
26
+ *
27
+ * A self-referral reports nothing either: internal navigation is the bulk of any site's
28
+ * traffic, and counting it would put the site's own domain at the top of its referrers
29
+ * breakdown forever. `selfHostname` is the event's own hostname, compared on the same terms
30
+ * (case-insensitively, `www.` stripped). The `source` dimension reads the same absence as its
31
+ * `direct` channel.
32
+ */
33
+ const referrerHost = (raw, selfHostname) => {
34
+ if (typeof raw !== "string" || !raw) return;
35
+ let host;
36
+ try {
37
+ host = new URL(raw).hostname;
38
+ } catch {
39
+ return;
40
+ }
41
+ const bare = bareHost(host);
42
+ if (!bare || bare === bareHost(selfHostname)) return;
43
+ return bare.slice(0, 253);
44
+ };
45
+ //#endregion
46
+ export { referrerHost, storedReferrer };
47
+
48
+ //# sourceMappingURL=referrer.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"referrer.js","names":[],"sources":["../../../src/native/ingest/referrer.ts"],"sourcesContent":["import { MAX_QUERY_HOSTNAME_LENGTH, MAX_REFERRER_LENGTH } from '../../query/limits'\n\n/** A hostname as it is compared: lowercased, without a leading `www.`. */\nconst bareHost = (host: string): string => host.toLowerCase().replace(/^www\\./, '')\n\n/**\n * The referrer as it is stored: everything from the first `#` or `?` onwards removed, then\n * capped. A same-origin navigation puts the previous page's whole URL in `document.referrer`,\n * so the query string routinely carries a reset token, a session id or an email address that\n * has no business in an analytics row. Origin and path are kept verbatim, case included,\n * because they are what makes a referrer readable. The fragment goes first: a `?` after a\n * `#` belongs to the fragment, not to a query.\n *\n * An unparseable referrer is stripped on the same terms rather than trusted, and a value that\n * is not a string at all is dropped: the wire field is public and unvalidated, so a body\n * carrying `\"referrer\": {}` must cost the event its referrer, not the request its response.\n */\nexport const storedReferrer = (raw: unknown): string | undefined => {\n\tif (typeof raw !== 'string') {\n\t\treturn undefined\n\t}\n\tconst stripped = raw.split('#')[0]?.split('?')[0]\n\treturn stripped ? stripped.slice(0, MAX_REFERRER_LENGTH) : undefined\n}\n\n/**\n * The referrer's bare host, which is what the `referrer` dimension buckets and reads by:\n * lowercased, without scheme, port, path, query or a leading `www.`. Nothing is reported for\n * a missing, non-string, hostless or unparseable referrer, so the event contributes no\n * referrer bucket.\n *\n * A self-referral reports nothing either: internal navigation is the bulk of any site's\n * traffic, and counting it would put the site's own domain at the top of its referrers\n * breakdown forever. `selfHostname` is the event's own hostname, compared on the same terms\n * (case-insensitively, `www.` stripped). The `source` dimension reads the same absence as its\n * `direct` channel.\n */\nexport const referrerHost = (raw: unknown, selfHostname: string): string | undefined => {\n\tif (typeof raw !== 'string' || !raw) {\n\t\treturn undefined\n\t}\n\tlet host: string\n\ttry {\n\t\thost = new URL(raw).hostname\n\t} catch {\n\t\treturn undefined\n\t}\n\tconst bare = bareHost(host)\n\tif (!bare || bare === bareHost(selfHostname)) {\n\t\treturn undefined\n\t}\n\treturn bare.slice(0, MAX_QUERY_HOSTNAME_LENGTH)\n}\n"],"mappings":";;AAGA,MAAM,YAAY,SAAyB,KAAK,YAAY,EAAE,QAAQ,UAAU,EAAE;;;;;;;;;;;;;AAclF,MAAa,kBAAkB,QAAqC;CACnE,IAAI,OAAO,QAAQ,UAClB;CAED,MAAM,WAAW,IAAI,MAAM,GAAG,EAAE,IAAI,MAAM,GAAG,EAAE;CAC/C,OAAO,WAAW,SAAS,MAAM,GAAA,GAAsB,IAAI,KAAA;AAC5D;;;;;;;;;;;;;AAcA,MAAa,gBAAgB,KAAc,iBAA6C;CACvF,IAAI,OAAO,QAAQ,YAAY,CAAC,KAC/B;CAED,IAAI;CACJ,IAAI;EACH,OAAO,IAAI,IAAI,GAAG,EAAE;CACrB,QAAQ;EACP;CACD;CACA,MAAM,OAAO,SAAS,IAAI;CAC1B,IAAI,CAAC,QAAQ,SAAS,SAAS,YAAY,GAC1C;CAED,OAAO,KAAK,MAAM,GAAA,GAA4B;AAC/C"}
@@ -0,0 +1,57 @@
1
+ /** Dot-separated labels, which is also every IPv4 literal. */
2
+ const DNS_NAME = /^[a-z0-9_-]+(\.[a-z0-9_-]+)*$/;
3
+ /** An IPv6 literal as a `Host` header spells it, minus the brackets: hex groups and colons. */
4
+ const IPV6 = /^[0-9a-f]{0,4}(:[0-9a-f]{0,4}){2,7}$/;
5
+ /**
6
+ * The one shape a hostname has anywhere in this plugin: config entries, `platformHostnames`,
7
+ * the host a request carried and a resolver's answer are all held to it. A host that can only
8
+ * be spelled one way can only open one rollup bucket family, and nothing prunes those, so a
9
+ * public endpoint that accepted several spellings of one name would hand a client an unbounded
10
+ * write.
11
+ */
12
+ const isHostname = (value) => value.length > 0 && value.length <= 253 && (DNS_NAME.test(value) || IPV6.test(value));
13
+ /** `host[:port]`, or the bracketed IPv6 form a `Host` header uses, which loses its brackets. */
14
+ const stripPort = (value) => {
15
+ const bracketed = /^\[([^\]]*)\](?::\d+)?$/.exec(value);
16
+ if (bracketed) return bracketed[1] ?? "";
17
+ return /^([^:]*)(?::\d+)?$/.exec(value)?.[1] ?? value;
18
+ };
19
+ /**
20
+ * A hostname as it is stored and compared: lowercased, without port, brackets or trailing root
21
+ * dots. Null for anything that is not {@link isHostname} afterwards, so a caller drops it
22
+ * rather than opening a rollup bucket family for junk.
23
+ */
24
+ const normalizeHostname = (value) => {
25
+ const raw = value?.trim().toLowerCase();
26
+ if (!raw) return null;
27
+ const host = stripPort(raw).replace(/\.+$/, "");
28
+ return isHostname(host) ? host : null;
29
+ };
30
+ /**
31
+ * The host the request itself carries: the `x-forwarded-host` entry `n` from the right where
32
+ * `n` proxy hops are trusted, which is the value the outermost trusted proxy wrote, else the
33
+ * `Host` header. Counting from the left would read the attacker-controlled end, since a proxy
34
+ * that appends rather than replaces keeps whatever the client sent ahead of its own value.
35
+ *
36
+ * `Host` is the fallback whenever the forwarded chain yields nothing usable, whether it is
37
+ * shorter than the trusted count or carries junk: the peer is still the trusted proxy, so
38
+ * `Host` is what that proxy sent.
39
+ *
40
+ * The `Origin` header is deliberately never read: a scripted client can pair a valid `Host`
41
+ * with any `Origin` it likes and mint unlimited hostnames inside one scope, which is the hole
42
+ * request attribution exists to close. A split deployment whose page host differs from its API
43
+ * host validates `Origin` itself, through the `hostname` resolver form.
44
+ */
45
+ const requestHostname = (headers, opts) => {
46
+ const hops = opts.trustedProxyHops ?? 0;
47
+ if (hops >= 1) {
48
+ const chain = (headers.get("x-forwarded-host") ?? "").split(",").map((entry) => entry.trim()).filter(Boolean);
49
+ const forwarded = normalizeHostname(chain[chain.length - hops]);
50
+ if (forwarded) return forwarded;
51
+ }
52
+ return normalizeHostname(headers.get("host"));
53
+ };
54
+ //#endregion
55
+ export { isHostname, normalizeHostname, requestHostname };
56
+
57
+ //# sourceMappingURL=requestHost.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"requestHost.js","names":[],"sources":["../../../src/native/ingest/requestHost.ts"],"sourcesContent":["/** Longest legal DNS name, and the cap every stored hostname carries. */\nexport const MAX_HOSTNAME_LENGTH = 253\n\n/** Dot-separated labels, which is also every IPv4 literal. */\nconst DNS_NAME = /^[a-z0-9_-]+(\\.[a-z0-9_-]+)*$/\n\n/** An IPv6 literal as a `Host` header spells it, minus the brackets: hex groups and colons. */\nconst IPV6 = /^[0-9a-f]{0,4}(:[0-9a-f]{0,4}){2,7}$/\n\n/**\n * The one shape a hostname has anywhere in this plugin: config entries, `platformHostnames`,\n * the host a request carried and a resolver's answer are all held to it. A host that can only\n * be spelled one way can only open one rollup bucket family, and nothing prunes those, so a\n * public endpoint that accepted several spellings of one name would hand a client an unbounded\n * write.\n */\nexport const isHostname = (value: string): boolean =>\n\tvalue.length > 0 &&\n\tvalue.length <= MAX_HOSTNAME_LENGTH &&\n\t(DNS_NAME.test(value) || IPV6.test(value))\n\n/** `host[:port]`, or the bracketed IPv6 form a `Host` header uses, which loses its brackets. */\nconst stripPort = (value: string): string => {\n\tconst bracketed = /^\\[([^\\]]*)\\](?::\\d+)?$/.exec(value)\n\tif (bracketed) {\n\t\treturn bracketed[1] ?? ''\n\t}\n\tconst named = /^([^:]*)(?::\\d+)?$/.exec(value)\n\treturn named?.[1] ?? value\n}\n\n/**\n * A hostname as it is stored and compared: lowercased, without port, brackets or trailing root\n * dots. Null for anything that is not {@link isHostname} afterwards, so a caller drops it\n * rather than opening a rollup bucket family for junk.\n */\nexport const normalizeHostname = (value: string | null | undefined): string | null => {\n\tconst raw = value?.trim().toLowerCase()\n\tif (!raw) {\n\t\treturn null\n\t}\n\t// Every trailing dot rather than one: `example.com.` and `example.com..` name the same\n\t// host, and each extra spelling left standing would be its own bucket family.\n\tconst host = stripPort(raw).replace(/\\.+$/, '')\n\treturn isHostname(host) ? host : null\n}\n\nexport interface RequestHostnameOptions {\n\t/** Trusted proxies in front of the app; `x-forwarded-host` is only read at one or more. */\n\ttrustedProxyHops?: number\n}\n\n/**\n * The host the request itself carries: the `x-forwarded-host` entry `n` from the right where\n * `n` proxy hops are trusted, which is the value the outermost trusted proxy wrote, else the\n * `Host` header. Counting from the left would read the attacker-controlled end, since a proxy\n * that appends rather than replaces keeps whatever the client sent ahead of its own value.\n *\n * `Host` is the fallback whenever the forwarded chain yields nothing usable, whether it is\n * shorter than the trusted count or carries junk: the peer is still the trusted proxy, so\n * `Host` is what that proxy sent.\n *\n * The `Origin` header is deliberately never read: a scripted client can pair a valid `Host`\n * with any `Origin` it likes and mint unlimited hostnames inside one scope, which is the hole\n * request attribution exists to close. A split deployment whose page host differs from its API\n * host validates `Origin` itself, through the `hostname` resolver form.\n */\nexport const requestHostname = (headers: Headers, opts: RequestHostnameOptions): string | null => {\n\tconst hops = opts.trustedProxyHops ?? 0\n\tif (hops >= 1) {\n\t\tconst chain = (headers.get('x-forwarded-host') ?? '')\n\t\t\t.split(',')\n\t\t\t.map((entry) => entry.trim())\n\t\t\t.filter(Boolean)\n\t\tconst forwarded = normalizeHostname(chain[chain.length - hops])\n\t\tif (forwarded) {\n\t\t\treturn forwarded\n\t\t}\n\t}\n\treturn normalizeHostname(headers.get('host'))\n}\n"],"mappings":";AAIA,MAAM,WAAW;;AAGjB,MAAM,OAAO;;;;;;;;AASb,MAAa,cAAc,UAC1B,MAAM,SAAS,KACf,MAAM,UAAA,QACL,SAAS,KAAK,KAAK,KAAK,KAAK,KAAK,KAAK;;AAGzC,MAAM,aAAa,UAA0B;CAC5C,MAAM,YAAY,0BAA0B,KAAK,KAAK;CACtD,IAAI,WACH,OAAO,UAAU,MAAM;CAGxB,OADc,qBAAqB,KAAK,KAC7B,IAAI,MAAM;AACtB;;;;;;AAOA,MAAa,qBAAqB,UAAoD;CACrF,MAAM,MAAM,OAAO,KAAK,EAAE,YAAY;CACtC,IAAI,CAAC,KACJ,OAAO;CAIR,MAAM,OAAO,UAAU,GAAG,EAAE,QAAQ,QAAQ,EAAE;CAC9C,OAAO,WAAW,IAAI,IAAI,OAAO;AAClC;;;;;;;;;;;;;;;;AAsBA,MAAa,mBAAmB,SAAkB,SAAgD;CACjG,MAAM,OAAO,KAAK,oBAAoB;CACtC,IAAI,QAAQ,GAAG;EACd,MAAM,SAAS,QAAQ,IAAI,kBAAkB,KAAK,IAChD,MAAM,GAAG,EACT,KAAK,UAAU,MAAM,KAAK,CAAC,EAC3B,OAAO,OAAO;EAChB,MAAM,YAAY,kBAAkB,MAAM,MAAM,SAAS,KAAK;EAC9D,IAAI,WACH,OAAO;CAET;CACA,OAAO,kBAAkB,QAAQ,IAAI,MAAM,CAAC;AAC7C"}
@@ -0,0 +1,29 @@
1
+ import { PayloadRequest } from "payload";
2
+
3
+ //#region src/native/ingest/resolveHostname.d.ts
4
+ /**
5
+ * Decides the hostname an event is stored under, or null to drop it. `claimed` is what the
6
+ * body sent, which is never trusted on its own; `scope` is the scope the request already
7
+ * resolved to, so a split deployment can validate `Origin` against that tenant's own domains.
8
+ *
9
+ * The answer must be a hostname: it is normalized and then held to the same shape a request
10
+ * host is, and anything else (a slug, a tenant id, free text) drops the event rather than
11
+ * storing per-event text no rollup family can ever be pruned from.
12
+ *
13
+ * Distinct from the binding `HostnameResolver`, which names the hostname a document is read
14
+ * under rather than the one an event is written under.
15
+ */
16
+ type EventHostnameResolver = (args: {
17
+ claimed: string | undefined;
18
+ req: PayloadRequest;
19
+ scope: string | null;
20
+ }) => string | null | Promise<string | null>;
21
+ /**
22
+ * `'request'` stores the host the request carried. A list stores the request host only when it
23
+ * is one of those, for a single-site install behind no host validation. A function decides for
24
+ * itself.
25
+ */
26
+ type HostnameOption = 'request' | string[] | EventHostnameResolver;
27
+ //#endregion
28
+ export { EventHostnameResolver, HostnameOption };
29
+ //# sourceMappingURL=resolveHostname.d.ts.map
@@ -0,0 +1,52 @@
1
+ import { isHostname, normalizeHostname, requestHostname } from "./requestHost.js";
2
+ //#region src/native/ingest/resolveHostname.ts
3
+ /**
4
+ * Config-time list validation: entries are lowercased here, so the ingest compare is exact.
5
+ * The port is not stripped the way a request host's is, because an entry carrying one would
6
+ * otherwise be accepted and then silently never match what is stored.
7
+ */
8
+ const hostnameSet = (values, option) => {
9
+ const hosts = /* @__PURE__ */ new Set();
10
+ for (const value of values ?? []) {
11
+ const host = typeof value === "string" ? value.trim().toLowerCase().replace(/\.+$/, "") : "";
12
+ if (!isHostname(host)) throw new Error(`analytics: ${option} entries must each be a bare hostname, got "${String(value)}"`);
13
+ hosts.add(host);
14
+ }
15
+ return hosts;
16
+ };
17
+ const resolveHostnameOption = (option) => {
18
+ if (option === void 0 || option === "request") return { kind: "request" };
19
+ if (typeof option === "function") return {
20
+ kind: "resolver",
21
+ resolve: option
22
+ };
23
+ if (!Array.isArray(option)) throw new Error(`analytics: hostname must be "request", a list of hostnames, or a resolver, got ${typeof option}`);
24
+ if (option.length === 0) throw new Error("analytics: hostname must name at least one hostname, or every event drops");
25
+ return {
26
+ kind: "list",
27
+ hosts: hostnameSet(option, "hostname")
28
+ };
29
+ };
30
+ /**
31
+ * The hostname to store for one event, or null to drop it. A resolver that throws drops the
32
+ * event too: ingest is a public path, so a broken lookup loses the event rather than the
33
+ * response.
34
+ */
35
+ const resolveEventHostname = async ({ option, claimed, req, scope, trustedProxyHops }) => {
36
+ const host = requestHostname(req.headers, { trustedProxyHops });
37
+ if (option.kind === "request") return host;
38
+ if (option.kind === "list") return host && option.hosts.has(host) ? host : null;
39
+ try {
40
+ return normalizeHostname(await option.resolve({
41
+ claimed,
42
+ req,
43
+ scope
44
+ }));
45
+ } catch {
46
+ return null;
47
+ }
48
+ };
49
+ //#endregion
50
+ export { hostnameSet, resolveEventHostname, resolveHostnameOption };
51
+
52
+ //# sourceMappingURL=resolveHostname.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"resolveHostname.js","names":[],"sources":["../../../src/native/ingest/resolveHostname.ts"],"sourcesContent":["import type { PayloadRequest } from 'payload'\nimport { isHostname, normalizeHostname, requestHostname } from './requestHost'\n\n/**\n * Decides the hostname an event is stored under, or null to drop it. `claimed` is what the\n * body sent, which is never trusted on its own; `scope` is the scope the request already\n * resolved to, so a split deployment can validate `Origin` against that tenant's own domains.\n *\n * The answer must be a hostname: it is normalized and then held to the same shape a request\n * host is, and anything else (a slug, a tenant id, free text) drops the event rather than\n * storing per-event text no rollup family can ever be pruned from.\n *\n * Distinct from the binding `HostnameResolver`, which names the hostname a document is read\n * under rather than the one an event is written under.\n */\nexport type EventHostnameResolver = (args: {\n\tclaimed: string | undefined\n\treq: PayloadRequest\n\tscope: string | null\n}) => string | null | Promise<string | null>\n\n/**\n * `'request'` stores the host the request carried. A list stores the request host only when it\n * is one of those, for a single-site install behind no host validation. A function decides for\n * itself.\n */\nexport type HostnameOption = 'request' | string[] | EventHostnameResolver\n\nexport type ResolvedHostnameOption =\n\t| { kind: 'request' }\n\t| { kind: 'list'; hosts: ReadonlySet<string> }\n\t| { kind: 'resolver'; resolve: EventHostnameResolver }\n\n/**\n * Config-time list validation: entries are lowercased here, so the ingest compare is exact.\n * The port is not stripped the way a request host's is, because an entry carrying one would\n * otherwise be accepted and then silently never match what is stored.\n */\nexport const hostnameSet = (values: string[] | undefined, option: string): ReadonlySet<string> => {\n\tconst hosts = new Set<string>()\n\tfor (const value of values ?? []) {\n\t\tconst host = typeof value === 'string' ? value.trim().toLowerCase().replace(/\\.+$/, '') : ''\n\t\tif (!isHostname(host)) {\n\t\t\tthrow new Error(\n\t\t\t\t`analytics: ${option} entries must each be a bare hostname, got \"${String(value)}\"`\n\t\t\t)\n\t\t}\n\t\thosts.add(host)\n\t}\n\treturn hosts\n}\n\nexport const resolveHostnameOption = (\n\toption: HostnameOption | undefined\n): ResolvedHostnameOption => {\n\tif (option === undefined || option === 'request') {\n\t\treturn { kind: 'request' }\n\t}\n\tif (typeof option === 'function') {\n\t\treturn { kind: 'resolver', resolve: option }\n\t}\n\tif (!Array.isArray(option)) {\n\t\tthrow new Error(\n\t\t\t`analytics: hostname must be \"request\", a list of hostnames, or a resolver, got ${typeof option}`\n\t\t)\n\t}\n\tif (option.length === 0) {\n\t\tthrow new Error('analytics: hostname must name at least one hostname, or every event drops')\n\t}\n\treturn { kind: 'list', hosts: hostnameSet(option, 'hostname') }\n}\n\nexport interface ResolveEventHostnameArgs {\n\toption: ResolvedHostnameOption\n\tclaimed: string | undefined\n\treq: PayloadRequest\n\tscope: string | null\n\ttrustedProxyHops?: number\n}\n\n/**\n * The hostname to store for one event, or null to drop it. A resolver that throws drops the\n * event too: ingest is a public path, so a broken lookup loses the event rather than the\n * response.\n */\nexport const resolveEventHostname = async ({\n\toption,\n\tclaimed,\n\treq,\n\tscope,\n\ttrustedProxyHops,\n}: ResolveEventHostnameArgs): Promise<string | null> => {\n\tconst host = requestHostname(req.headers, { trustedProxyHops })\n\tif (option.kind === 'request') {\n\t\treturn host\n\t}\n\tif (option.kind === 'list') {\n\t\treturn host && option.hosts.has(host) ? host : null\n\t}\n\ttry {\n\t\treturn normalizeHostname(await option.resolve({ claimed, req, scope }))\n\t} catch {\n\t\treturn null\n\t}\n}\n"],"mappings":";;;;;;;AAsCA,MAAa,eAAe,QAA8B,WAAwC;CACjG,MAAM,wBAAQ,IAAI,IAAY;CAC9B,KAAK,MAAM,SAAS,UAAU,CAAC,GAAG;EACjC,MAAM,OAAO,OAAO,UAAU,WAAW,MAAM,KAAK,EAAE,YAAY,EAAE,QAAQ,QAAQ,EAAE,IAAI;EAC1F,IAAI,CAAC,WAAW,IAAI,GACnB,MAAM,IAAI,MACT,cAAc,OAAO,8CAA8C,OAAO,KAAK,EAAE,EAClF;EAED,MAAM,IAAI,IAAI;CACf;CACA,OAAO;AACR;AAEA,MAAa,yBACZ,WAC4B;CAC5B,IAAI,WAAW,KAAA,KAAa,WAAW,WACtC,OAAO,EAAE,MAAM,UAAU;CAE1B,IAAI,OAAO,WAAW,YACrB,OAAO;EAAE,MAAM;EAAY,SAAS;CAAO;CAE5C,IAAI,CAAC,MAAM,QAAQ,MAAM,GACxB,MAAM,IAAI,MACT,kFAAkF,OAAO,QAC1F;CAED,IAAI,OAAO,WAAW,GACrB,MAAM,IAAI,MAAM,2EAA2E;CAE5F,OAAO;EAAE,MAAM;EAAQ,OAAO,YAAY,QAAQ,UAAU;CAAE;AAC/D;;;;;;AAeA,MAAa,uBAAuB,OAAO,EAC1C,QACA,SACA,KACA,OACA,uBACuD;CACvD,MAAM,OAAO,gBAAgB,IAAI,SAAS,EAAE,iBAAiB,CAAC;CAC9D,IAAI,OAAO,SAAS,WACnB,OAAO;CAER,IAAI,OAAO,SAAS,QACnB,OAAO,QAAQ,OAAO,MAAM,IAAI,IAAI,IAAI,OAAO;CAEhD,IAAI;EACH,OAAO,kBAAkB,MAAM,OAAO,QAAQ;GAAE;GAAS;GAAK;EAAM,CAAC,CAAC;CACvE,QAAQ;EACP,OAAO;CACR;AACD"}
@@ -1,14 +1,39 @@
1
1
  import { randomBytes } from "node:crypto";
2
2
  //#region src/native/ingest/salt.ts
3
+ const DAY_MS = 864e5;
4
+ /**
5
+ * The KV key a day's visitor salt lives under. Keyed by UTC day so the salt rotates at
6
+ * midnight; payload.kv has no TTL, so old days are deleted by this name.
7
+ */
8
+ const saltKey = (day) => `analytics:salt:${day.toISOString().slice(0, 10)}`;
9
+ /**
10
+ * An event arriving just before midnight is still hashed with yesterday's salt, so the sweep
11
+ * starts two days back. A week is what one ingest can reach without a listing; the nightly
12
+ * task covers a wider window when an install runs it.
13
+ */
14
+ const SWEEP_FIRST_DAY = 2;
15
+ const SWEEP_LAST_DAY = 8;
16
+ /**
17
+ * Deletes the salts a new day has made unreadable, without waiting on them: the salts must not
18
+ * accumulate forever on an install that runs no jobs, and no visitor hash depends on this
19
+ * finishing. Keys go by computed name, so a day already gone is a no-op on every kv adapter.
20
+ */
21
+ const sweepOldSalts = (payload, now) => {
22
+ for (let day = SWEEP_FIRST_DAY; day <= SWEEP_LAST_DAY; day++) {
23
+ const stale = saltKey(/* @__PURE__ */ new Date(now.getTime() - day * DAY_MS));
24
+ Promise.resolve().then(() => payload.kv.delete(stale)).catch(() => void 0);
25
+ }
26
+ };
3
27
  async function dailySalt(payload, now) {
4
- const key = `analytics:salt:${now.toISOString().slice(0, 10)}`;
28
+ const key = saltKey(now);
5
29
  const existing = await payload.kv.get(key);
6
30
  if (existing) return existing.salt;
7
31
  const salt = randomBytes(16).toString("hex");
8
32
  await payload.kv.set(key, { salt });
33
+ sweepOldSalts(payload, now);
9
34
  return salt;
10
35
  }
11
36
  //#endregion
12
- export { dailySalt };
37
+ export { dailySalt, saltKey };
13
38
 
14
39
  //# sourceMappingURL=salt.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"salt.js","names":[],"sources":["../../../src/native/ingest/salt.ts"],"sourcesContent":["import { randomBytes } from 'node:crypto'\nimport type { Payload } from 'payload'\n\n// Salt is keyed by UTC day so it rotates at midnight; payload.kv has no native TTL,\n// hence the date-keyed approach (old salts are pruned in a later plan).\nexport async function dailySalt(payload: Payload, now: Date): Promise<string> {\n\tconst day = now.toISOString().slice(0, 10)\n\tconst key = `analytics:salt:${day}`\n\tconst existing = await payload.kv.get<{ salt: string }>(key)\n\tif (existing) {\n\t\treturn existing.salt\n\t}\n\tconst salt = randomBytes(16).toString('hex')\n\tawait payload.kv.set(key, { salt })\n\treturn salt\n}\n"],"mappings":";;AAKA,eAAsB,UAAU,SAAkB,KAA4B;CAE7E,MAAM,MAAM,kBADA,IAAI,YAAY,EAAE,MAAM,GAAG,EACP;CAChC,MAAM,WAAW,MAAM,QAAQ,GAAG,IAAsB,GAAG;CAC3D,IAAI,UACH,OAAO,SAAS;CAEjB,MAAM,OAAO,YAAY,EAAE,EAAE,SAAS,KAAK;CAC3C,MAAM,QAAQ,GAAG,IAAI,KAAK,EAAE,KAAK,CAAC;CAClC,OAAO;AACR"}
1
+ {"version":3,"file":"salt.js","names":[],"sources":["../../../src/native/ingest/salt.ts"],"sourcesContent":["import { randomBytes } from 'node:crypto'\nimport type { Payload } from 'payload'\n\nconst DAY_MS = 86_400_000\n\n/**\n * The KV key a day's visitor salt lives under. Keyed by UTC day so the salt rotates at\n * midnight; payload.kv has no TTL, so old days are deleted by this name.\n */\nexport const saltKey = (day: Date): string => `analytics:salt:${day.toISOString().slice(0, 10)}`\n\n/**\n * An event arriving just before midnight is still hashed with yesterday's salt, so the sweep\n * starts two days back. A week is what one ingest can reach without a listing; the nightly\n * task covers a wider window when an install runs it.\n */\nconst SWEEP_FIRST_DAY = 2\nconst SWEEP_LAST_DAY = 8\n\n/**\n * Deletes the salts a new day has made unreadable, without waiting on them: the salts must not\n * accumulate forever on an install that runs no jobs, and no visitor hash depends on this\n * finishing. Keys go by computed name, so a day already gone is a no-op on every kv adapter.\n */\nconst sweepOldSalts = (payload: Payload, now: Date): void => {\n\tfor (let day = SWEEP_FIRST_DAY; day <= SWEEP_LAST_DAY; day++) {\n\t\tconst stale = saltKey(new Date(now.getTime() - day * DAY_MS))\n\t\t// The call itself is inside the thenable, so a kv adapter that throws synchronously\n\t\t// fails the sweep rather than the ingest that triggered it.\n\t\tvoid Promise.resolve()\n\t\t\t.then(() => payload.kv.delete(stale))\n\t\t\t.catch(() => undefined)\n\t}\n}\n\nexport async function dailySalt(payload: Payload, now: Date): Promise<string> {\n\tconst key = saltKey(now)\n\tconst existing = await payload.kv.get<{ salt: string }>(key)\n\tif (existing) {\n\t\treturn existing.salt\n\t}\n\tconst salt = randomBytes(16).toString('hex')\n\tawait payload.kv.set(key, { salt })\n\tsweepOldSalts(payload, now)\n\treturn salt\n}\n"],"mappings":";;AAGA,MAAM,SAAS;;;;;AAMf,MAAa,WAAW,QAAsB,kBAAkB,IAAI,YAAY,EAAE,MAAM,GAAG,EAAE;;;;;;AAO7F,MAAM,kBAAkB;AACxB,MAAM,iBAAiB;;;;;;AAOvB,MAAM,iBAAiB,SAAkB,QAAoB;CAC5D,KAAK,IAAI,MAAM,iBAAiB,OAAO,gBAAgB,OAAO;EAC7D,MAAM,QAAQ,wBAAQ,IAAI,KAAK,IAAI,QAAQ,IAAI,MAAM,MAAM,CAAC;EAG5D,QAAa,QAAQ,EACnB,WAAW,QAAQ,GAAG,OAAO,KAAK,CAAC,EACnC,YAAY,KAAA,CAAS;CACxB;AACD;AAEA,eAAsB,UAAU,SAAkB,KAA4B;CAC7E,MAAM,MAAM,QAAQ,GAAG;CACvB,MAAM,WAAW,MAAM,QAAQ,GAAG,IAAsB,GAAG;CAC3D,IAAI,UACH,OAAO,SAAS;CAEjB,MAAM,OAAO,YAAY,EAAE,EAAE,SAAS,KAAK;CAC3C,MAAM,QAAQ,GAAG,IAAI,KAAK,EAAE,KAAK,CAAC;CAClC,cAAc,SAAS,GAAG;CAC1B,OAAO;AACR"}
@@ -0,0 +1,20 @@
1
+ import { ServerEventInput, ServerTrackOptions } from "../../core/serverEvent.js";
2
+ import { Payload } from "payload";
3
+
4
+ //#region src/native/ingest/serverTrack.d.ts
5
+ /**
6
+ * Records an analytics event from server code: a webhook, a job, a server action. The event
7
+ * goes through the same normalization, sanitization and goal matching a browser event does.
8
+ * Pass `opts.req` whenever there is a request behind the event, so it inherits that request's
9
+ * attribution, scope and reporting timezone.
10
+ *
11
+ * `event.scope` overrides the request's scope; it is ignored on an unscoped install and is
12
+ * never checked against the scopes that exist, so the caller owns what it stamps.
13
+ *
14
+ * Needs the native adapter: a provider slot (Plausible, GA4) has no server ingestion seam
15
+ * here yet, so an install without the native adapter throws rather than dropping the event.
16
+ */
17
+ declare const trackServerEvent: (payload: Payload, event: ServerEventInput, opts?: ServerTrackOptions) => Promise<void>;
18
+ //#endregion
19
+ export { trackServerEvent };
20
+ //# sourceMappingURL=serverTrack.d.ts.map
@@ -0,0 +1,109 @@
1
+ import { getRuntime } from "../../plugin/runtime.js";
2
+ import { AnalyticsTrackError } from "../../core/serverEvent.js";
3
+ import { SERVER_USER_AGENT } from "./device.js";
4
+ import { flushBatch } from "./flushBatch.js";
5
+ import { normalizeEvent } from "./normalizeEvent.js";
6
+ import { dailySalt } from "./salt.js";
7
+ import { rawEventError } from "./validate.js";
8
+ import { createLocalReq } from "payload";
9
+ //#region src/native/ingest/serverTrack.ts
10
+ /**
11
+ * The originating request's own headers, so a server event attributes exactly like the
12
+ * browser event it stands in for: the platform's geo headers reach the geo resolver and the
13
+ * visitor hashes to the same person. Explicit `ip` / `userAgent` overlay them.
14
+ *
15
+ * With no request and no user agent the synthetic server agent stands in, which hashes every
16
+ * such event in a day to one visitor per site and reports no device at all.
17
+ */
18
+ const attributionHeaders = (event, req) => {
19
+ const headers = new Headers(req?.headers);
20
+ if (event.ip) headers.set("x-forwarded-for", event.ip);
21
+ if (event.userAgent) headers.set("user-agent", event.userAgent);
22
+ if (!headers.get("user-agent")) headers.set("user-agent", SERVER_USER_AGENT);
23
+ return headers;
24
+ };
25
+ const resolveScope = async (event, opts, resolvers) => {
26
+ if (!resolvers.scope) return;
27
+ if (event.scope !== void 0) return event.scope ?? "";
28
+ if (!opts?.req) return "";
29
+ return await resolvers.scope(opts.req) ?? "";
30
+ };
31
+ /**
32
+ * The native adapter's server-side ingestion, exposed as `adapter.ingest.track`. Same
33
+ * normalization, goal matching and write path the HTTP endpoint uses; only attribution and
34
+ * scope resolution differ, since there may be no request behind the event at all.
35
+ */
36
+ const makeServerTrack = (deps) => async (event, opts) => {
37
+ const payload = deps.getPayload();
38
+ if (!payload) throw new AnalyticsTrackError("analytics: trackServerEvent called before init");
39
+ const invalid = rawEventError(event, { requireHostname: true });
40
+ if (invalid) throw new AnalyticsTrackError(`analytics: trackServerEvent needs a valid "${invalid}"`);
41
+ const resolvers = deps.getResolvers();
42
+ const scope = await resolveScope(event, opts, resolvers);
43
+ let local;
44
+ const requestFor = async () => {
45
+ if (opts?.req) return opts.req;
46
+ local ??= await createLocalReq({}, payload);
47
+ return local;
48
+ };
49
+ const timezone = event.timezone ?? (resolvers.timezone ? await resolvers.timezone(await requestFor(), scope ?? null) : void 0);
50
+ const goals = resolvers.goals ? await resolvers.goals(await requestFor(), scope ?? null) : void 0;
51
+ const now = event.now ?? /* @__PURE__ */ new Date();
52
+ const stored = await normalizeEvent({
53
+ raw: {
54
+ type: event.type,
55
+ name: event.name,
56
+ path: event.path,
57
+ referrer: event.referrer,
58
+ query: event.query,
59
+ props: event.props,
60
+ value: event.value,
61
+ currency: event.currency
62
+ },
63
+ hostname: event.hostname,
64
+ headers: attributionHeaders(event, opts?.req),
65
+ geoResolver: deps.geoResolver,
66
+ salt: await dailySalt(payload, now),
67
+ now,
68
+ scope,
69
+ timezone,
70
+ goals,
71
+ trustedProxyHops: deps.getAttribution().trustedProxyHops
72
+ });
73
+ const buffer = deps.getBuffer();
74
+ if (!buffer) {
75
+ await flushBatch(payload, [stored]);
76
+ return;
77
+ }
78
+ buffer.add(stored);
79
+ if (opts?.flush) await buffer.flush();
80
+ };
81
+ /**
82
+ * The adapter {@link trackServerEvent} writes through: the first registered one with a server
83
+ * ingestion seam. Every caller that needs a second seam beside `track` (the hostname policy a
84
+ * goal action applies) reads it off this same adapter, so an event cannot be judged by one
85
+ * adapter and written by another. The registry here is the static config one, so a per-tenant
86
+ * runtime provider never supplies either seam.
87
+ */
88
+ const ingestAdapter = (payload) => getRuntime(payload)?.registry.all().find((adapter) => adapter.ingest?.track);
89
+ /**
90
+ * Records an analytics event from server code: a webhook, a job, a server action. The event
91
+ * goes through the same normalization, sanitization and goal matching a browser event does.
92
+ * Pass `opts.req` whenever there is a request behind the event, so it inherits that request's
93
+ * attribution, scope and reporting timezone.
94
+ *
95
+ * `event.scope` overrides the request's scope; it is ignored on an unscoped install and is
96
+ * never checked against the scopes that exist, so the caller owns what it stamps.
97
+ *
98
+ * Needs the native adapter: a provider slot (Plausible, GA4) has no server ingestion seam
99
+ * here yet, so an install without the native adapter throws rather than dropping the event.
100
+ */
101
+ const trackServerEvent = async (payload, event, opts) => {
102
+ const track = ingestAdapter(payload)?.ingest?.track;
103
+ if (!track) throw new AnalyticsTrackError("analytics: trackServerEvent needs the native adapter; provider-slot server tracking is not supported yet");
104
+ await track(event, opts);
105
+ };
106
+ //#endregion
107
+ export { ingestAdapter, makeServerTrack, trackServerEvent };
108
+
109
+ //# sourceMappingURL=serverTrack.js.map