@10x-media/analytics 1.0.0-beta.9 → 4.0.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (1273) hide show
  1. package/CHANGELOG.md +710 -0
  2. package/README.md +35 -36
  3. package/dist/access/adminUser.d.ts +15 -0
  4. package/dist/access/adminUser.js +13 -0
  5. package/dist/access/adminUser.js.map +1 -0
  6. package/dist/access/decideOnce.js +16 -0
  7. package/dist/access/decideOnce.js.map +1 -0
  8. package/dist/access/membership.d.ts +23 -0
  9. package/dist/access/membership.js +63 -0
  10. package/dist/access/membership.js.map +1 -0
  11. package/dist/access/principal.d.ts +37 -0
  12. package/dist/access/principal.js +29 -0
  13. package/dist/access/principal.js.map +1 -0
  14. package/dist/access/readGate.js +16 -0
  15. package/dist/access/readGate.js.map +1 -0
  16. package/dist/adapters/ga4/disableKey.js +19 -0
  17. package/dist/adapters/ga4/disableKey.js.map +1 -0
  18. package/dist/adapters/ga4/eventName.d.ts +2 -8
  19. package/dist/adapters/ga4/eventName.js +2 -8
  20. package/dist/adapters/ga4/eventName.js.map +1 -1
  21. package/dist/adapters/ga4/ga4.d.ts +24 -0
  22. package/dist/adapters/ga4/ga4.js +226 -122
  23. package/dist/adapters/ga4/ga4.js.map +1 -1
  24. package/dist/adapters/ga4/measurementId.js +2 -3
  25. package/dist/adapters/ga4/measurementId.js.map +1 -1
  26. package/dist/adapters/goalRead.js +15 -29
  27. package/dist/adapters/goalRead.js.map +1 -1
  28. package/dist/adapters/http/baseUrl.js +15 -0
  29. package/dist/adapters/http/baseUrl.js.map +1 -0
  30. package/dist/adapters/http/fetchJson.d.ts +19 -0
  31. package/dist/adapters/http/fetchJson.js +27 -8
  32. package/dist/adapters/http/fetchJson.js.map +1 -1
  33. package/dist/adapters/mapping.js +52 -0
  34. package/dist/adapters/mapping.js.map +1 -0
  35. package/dist/adapters/plausible/plausible.d.ts +25 -13
  36. package/dist/adapters/plausible/plausible.js +144 -124
  37. package/dist/adapters/plausible/plausible.js.map +1 -1
  38. package/dist/adapters/plausible/scriptId.js +19 -0
  39. package/dist/adapters/plausible/scriptId.js.map +1 -0
  40. package/dist/adapters/posthog/posthog.d.ts +33 -9
  41. package/dist/adapters/posthog/posthog.js +279 -121
  42. package/dist/adapters/posthog/posthog.js.map +1 -1
  43. package/dist/adapters/posthog/projectCheck.js +56 -0
  44. package/dist/adapters/posthog/projectCheck.js.map +1 -0
  45. package/dist/adapters/readTime.js +7 -0
  46. package/dist/adapters/readTime.js.map +1 -0
  47. package/dist/adapters/series.js +14 -8
  48. package/dist/adapters/series.js.map +1 -1
  49. package/dist/adapters/umami/umami.d.ts +19 -9
  50. package/dist/adapters/umami/umami.js +196 -166
  51. package/dist/adapters/umami/umami.js.map +1 -1
  52. package/dist/adapters/upstream.js +16 -0
  53. package/dist/adapters/upstream.js.map +1 -0
  54. package/dist/binding/report.d.ts +8 -0
  55. package/dist/binding/report.js +24 -0
  56. package/dist/binding/report.js.map +1 -0
  57. package/dist/binding/resolvePath.js +28 -25
  58. package/dist/binding/resolvePath.js.map +1 -1
  59. package/dist/binding/types.d.ts +14 -29
  60. package/dist/capture/captureRequest.js +28 -0
  61. package/dist/capture/captureRequest.js.map +1 -0
  62. package/dist/capture/exclusionEndpoint.js +98 -0
  63. package/dist/capture/exclusionEndpoint.js.map +1 -0
  64. package/dist/capture/exclusionPrelude.js +14 -0
  65. package/dist/capture/exclusionPrelude.js.map +1 -0
  66. package/dist/capture/exclusionToken.js +23 -0
  67. package/dist/capture/exclusionToken.js.map +1 -0
  68. package/dist/capture/jsLiteral.js +19 -0
  69. package/dist/capture/jsLiteral.js.map +1 -0
  70. package/dist/capture/mountPath.js +2 -3
  71. package/dist/capture/mountPath.js.map +1 -1
  72. package/dist/capture/proxyEndpoint.js +49 -92
  73. package/dist/capture/proxyEndpoint.js.map +1 -1
  74. package/dist/capture/proxyRoutes.js +58 -21
  75. package/dist/capture/proxyRoutes.js.map +1 -1
  76. package/dist/capture/relay.js +91 -0
  77. package/dist/capture/relay.js.map +1 -0
  78. package/dist/capture/requestBody.js +2 -6
  79. package/dist/capture/requestBody.js.map +1 -1
  80. package/dist/capture/requestTrust.js +45 -0
  81. package/dist/capture/requestTrust.js.map +1 -0
  82. package/dist/capture/sameSite.js +40 -0
  83. package/dist/capture/sameSite.js.map +1 -0
  84. package/dist/capture/slots.js +50 -25
  85. package/dist/capture/slots.js.map +1 -1
  86. package/dist/capture/trackerConfig.js +131 -36
  87. package/dist/capture/trackerConfig.js.map +1 -1
  88. package/dist/capture/trackerEndpoint.js +22 -21
  89. package/dist/capture/trackerEndpoint.js.map +1 -1
  90. package/dist/capture/withoutConsent.js +91 -0
  91. package/dist/capture/withoutConsent.js.map +1 -0
  92. package/dist/charts/BarList.d.ts +27 -13
  93. package/dist/charts/BarList.js +38 -83
  94. package/dist/charts/BarList.js.map +1 -1
  95. package/dist/charts/TrendChart.d.ts +40 -7
  96. package/dist/charts/TrendChart.js +243 -215
  97. package/dist/charts/TrendChart.js.map +1 -1
  98. package/dist/charts/bars.d.ts +17 -1
  99. package/dist/charts/bars.js +12 -11
  100. package/dist/charts/bars.js.map +1 -1
  101. package/dist/charts/bucket.js +106 -73
  102. package/dist/charts/bucket.js.map +1 -1
  103. package/dist/charts/inProgress.js +22 -0
  104. package/dist/charts/inProgress.js.map +1 -0
  105. package/dist/charts/series.d.ts +15 -0
  106. package/dist/charts/series.js +123 -0
  107. package/dist/charts/series.js.map +1 -0
  108. package/dist/charts/spline.js +91 -25
  109. package/dist/charts/spline.js.map +1 -1
  110. package/dist/charts/trendGeometry.js +91 -0
  111. package/dist/charts/trendGeometry.js.map +1 -0
  112. package/dist/core/adminOptions.d.ts +1 -0
  113. package/dist/core/adminOptions.js +198 -0
  114. package/dist/core/adminOptions.js.map +1 -0
  115. package/dist/core/budget.js +24 -0
  116. package/dist/core/budget.js.map +1 -0
  117. package/dist/core/cacheKey.d.ts +1 -0
  118. package/dist/core/cacheKey.js +48 -36
  119. package/dist/core/cacheKey.js.map +1 -1
  120. package/dist/core/cacheOptions.js +165 -0
  121. package/dist/core/cacheOptions.js.map +1 -0
  122. package/dist/core/capabilities.d.ts +24 -11
  123. package/dist/core/capabilities.js +96 -17
  124. package/dist/core/capabilities.js.map +1 -1
  125. package/dist/core/capture.d.ts +59 -26
  126. package/dist/core/captureOptions.d.ts +1 -0
  127. package/dist/core/captureOptions.js +347 -0
  128. package/dist/core/captureOptions.js.map +1 -0
  129. package/dist/core/clock.js +13 -0
  130. package/dist/core/clock.js.map +1 -0
  131. package/dist/core/collectionOption.d.ts +17 -0
  132. package/dist/core/collectionOption.js +105 -0
  133. package/dist/core/collectionOption.js.map +1 -0
  134. package/dist/core/collectionSlug.js +7 -0
  135. package/dist/core/collectionSlug.js.map +1 -0
  136. package/dist/core/contract.d.ts +321 -60
  137. package/dist/core/contract.js +7 -4
  138. package/dist/core/contract.js.map +1 -1
  139. package/dist/core/cron.js +57 -0
  140. package/dist/core/cron.js.map +1 -0
  141. package/dist/core/fetch.d.ts +17 -0
  142. package/dist/core/goalOptions.d.ts +1 -0
  143. package/dist/core/goalOptions.js +166 -0
  144. package/dist/core/goalOptions.js.map +1 -0
  145. package/dist/core/granularity.js +3 -2
  146. package/dist/core/granularity.js.map +1 -1
  147. package/dist/core/guards.js +17 -0
  148. package/dist/core/guards.js.map +1 -0
  149. package/dist/core/jobs.d.ts +40 -0
  150. package/dist/core/jobs.js +132 -0
  151. package/dist/core/jobs.js.map +1 -0
  152. package/dist/core/legacyOptions.js +145 -0
  153. package/dist/core/legacyOptions.js.map +1 -0
  154. package/dist/core/metricAliases.js +81 -0
  155. package/dist/core/metricAliases.js.map +1 -0
  156. package/dist/core/metricValues.js +57 -0
  157. package/dist/core/metricValues.js.map +1 -0
  158. package/dist/core/monotonic.js +10 -0
  159. package/dist/core/monotonic.js.map +1 -0
  160. package/dist/core/optionChecks.js +51 -0
  161. package/dist/core/optionChecks.js.map +1 -0
  162. package/dist/core/options.d.ts +530 -152
  163. package/dist/core/options.js +158 -216
  164. package/dist/core/options.js.map +1 -1
  165. package/dist/core/registry.js +45 -5
  166. package/dist/core/registry.js.map +1 -1
  167. package/dist/core/scopeList.js +7 -9
  168. package/dist/core/scopeList.js.map +1 -1
  169. package/dist/core/scopeOptions.d.ts +1 -0
  170. package/dist/core/scopeOptions.js +114 -0
  171. package/dist/core/scopeOptions.js.map +1 -0
  172. package/dist/core/scopedRead.js +349 -36
  173. package/dist/core/scopedRead.js.map +1 -1
  174. package/dist/core/sdks.d.ts +81 -0
  175. package/dist/core/sdks.js +23 -0
  176. package/dist/core/sdks.js.map +1 -0
  177. package/dist/core/serverEvent.d.ts +50 -16
  178. package/dist/core/serverEvent.js.map +1 -1
  179. package/dist/core/siteAddress.js +20 -0
  180. package/dist/core/siteAddress.js.map +1 -0
  181. package/dist/core/sourceErrors.js +109 -0
  182. package/dist/core/sourceErrors.js.map +1 -0
  183. package/dist/core/sourceLabel.d.ts +10 -0
  184. package/dist/core/sourceLabel.js +63 -0
  185. package/dist/core/sourceLabel.js.map +1 -0
  186. package/dist/core/sourceOptions.js +107 -0
  187. package/dist/core/sourceOptions.js.map +1 -0
  188. package/dist/core/sourcePolicy.d.ts +55 -0
  189. package/dist/core/sourcePolicy.js +51 -0
  190. package/dist/core/sourcePolicy.js.map +1 -0
  191. package/dist/core/throttle.js +18 -0
  192. package/dist/core/throttle.js.map +1 -0
  193. package/dist/core/values.js +61 -0
  194. package/dist/core/values.js.map +1 -0
  195. package/dist/core/widgetSlugs.d.ts +17 -0
  196. package/dist/core/widgetSlugs.js +29 -0
  197. package/dist/core/widgetSlugs.js.map +1 -0
  198. package/dist/db/detachedWrite.js +36 -0
  199. package/dist/db/detachedWrite.js.map +1 -0
  200. package/dist/db/errors.js +182 -0
  201. package/dist/db/errors.js.map +1 -0
  202. package/dist/db/kind.js +32 -0
  203. package/dist/db/kind.js.map +1 -0
  204. package/dist/db/openTransaction.js +51 -0
  205. package/dist/db/openTransaction.js.map +1 -0
  206. package/dist/exports/adapters/contract.d.ts +15 -0
  207. package/dist/exports/adapters/ga4.d.ts +16 -1
  208. package/dist/exports/adapters/native.d.ts +29 -2
  209. package/dist/exports/adapters/native.js +5 -1
  210. package/dist/exports/adapters/plausible.d.ts +16 -1
  211. package/dist/exports/adapters/posthog.d.ts +16 -1
  212. package/dist/exports/adapters/umami.d.ts +16 -1
  213. package/dist/exports/attributes.d.ts +42 -0
  214. package/dist/exports/attributes.js +83 -0
  215. package/dist/exports/attributes.js.map +1 -0
  216. package/dist/exports/client.d.ts +43 -12
  217. package/dist/exports/client.js +22 -8
  218. package/dist/exports/geo.d.ts +4 -2
  219. package/dist/exports/geo.js +1 -1
  220. package/dist/exports/i18n.d.ts +2 -2
  221. package/dist/exports/i18n.js +2 -2
  222. package/dist/exports/migrations.d.ts +2 -0
  223. package/dist/exports/migrations.js +2 -0
  224. package/dist/exports/react.d.ts +5 -3
  225. package/dist/exports/react.js +1 -2
  226. package/dist/exports/routes.d.ts +19 -0
  227. package/dist/exports/routes.js +3 -0
  228. package/dist/exports/rsc.d.ts +32 -14
  229. package/dist/exports/rsc.js +11 -6
  230. package/dist/exports/site.d.ts +5 -0
  231. package/dist/exports/site.js +3 -0
  232. package/dist/exports/testing.d.ts +18 -0
  233. package/dist/exports/testing.js +3 -0
  234. package/dist/exports/tracker.d.ts +6 -18
  235. package/dist/exports/tracker.js +3 -12
  236. package/dist/exports/types.d.ts +45 -14
  237. package/dist/exports/types.js +6 -1
  238. package/dist/fields/AnalyticsPanelClient.js +265 -154
  239. package/dist/fields/AnalyticsPanelClient.js.map +1 -1
  240. package/dist/fields/AnalyticsPanelField.d.ts +19 -7
  241. package/dist/fields/AnalyticsPanelField.js +123 -30
  242. package/dist/fields/AnalyticsPanelField.js.map +1 -1
  243. package/dist/fields/AnalyticsStatField.d.ts +17 -6
  244. package/dist/fields/AnalyticsStatField.js +98 -63
  245. package/dist/fields/AnalyticsStatField.js.map +1 -1
  246. package/dist/fields/FieldShimmer.js +15 -0
  247. package/dist/fields/FieldShimmer.js.map +1 -0
  248. package/dist/fields/PanelContent.js +222 -0
  249. package/dist/fields/PanelContent.js.map +1 -0
  250. package/dist/fields/PanelList.js +82 -0
  251. package/dist/fields/PanelList.js.map +1 -0
  252. package/dist/fields/PanelLiveCounter.js +63 -0
  253. package/dist/fields/PanelLiveCounter.js.map +1 -0
  254. package/dist/fields/PanelSkeleton.js +63 -0
  255. package/dist/fields/PanelSkeleton.js.map +1 -0
  256. package/dist/fields/componentPaths.js +8 -0
  257. package/dist/fields/componentPaths.js.map +1 -0
  258. package/dist/fields/config/FilterDimensionSelectField.d.ts +2 -2
  259. package/dist/fields/config/FilterDimensionSelectField.js +26 -54
  260. package/dist/fields/config/FilterDimensionSelectField.js.map +1 -1
  261. package/dist/fields/config/FilterKeySelect.js +66 -0
  262. package/dist/fields/config/FilterKeySelect.js.map +1 -0
  263. package/dist/fields/config/FilterOperatorSelectField.d.ts +7 -2
  264. package/dist/fields/config/FilterOperatorSelectField.js +37 -53
  265. package/dist/fields/config/FilterOperatorSelectField.js.map +1 -1
  266. package/dist/fields/config/FilterValueField.d.ts +17 -0
  267. package/dist/fields/config/FilterValueField.js +130 -0
  268. package/dist/fields/config/FilterValueField.js.map +1 -0
  269. package/dist/fields/config/MetricSelectField.d.ts +5 -12
  270. package/dist/fields/config/MetricSelectField.js +18 -30
  271. package/dist/fields/config/MetricSelectField.js.map +1 -1
  272. package/dist/fields/config/OptionSelect.js +52 -0
  273. package/dist/fields/config/OptionSelect.js.map +1 -0
  274. package/dist/fields/config/SourceSelectField.js +16 -31
  275. package/dist/fields/config/SourceSelectField.js.map +1 -1
  276. package/dist/fields/config/fetchSources.d.ts +3 -0
  277. package/dist/fields/config/fetchSources.js +17 -23
  278. package/dist/fields/config/fetchSources.js.map +1 -1
  279. package/dist/fields/config/filterValues.js +106 -0
  280. package/dist/fields/config/filterValues.js.map +1 -0
  281. package/dist/fields/config/narrow.js +8 -10
  282. package/dist/fields/config/narrow.js.map +1 -1
  283. package/dist/fields/config/retiredPickers.d.ts +45 -0
  284. package/dist/fields/config/retiredPickers.js +46 -0
  285. package/dist/fields/config/retiredPickers.js.map +1 -0
  286. package/dist/fields/config/scopedFields.d.ts +40 -0
  287. package/dist/fields/config/scopedFields.js +68 -0
  288. package/dist/fields/config/scopedFields.js.map +1 -0
  289. package/dist/fields/config/toSelectOption.js +13 -7
  290. package/dist/fields/config/toSelectOption.js.map +1 -1
  291. package/dist/fields/config/useAnalyticsSources.d.ts +5 -7
  292. package/dist/fields/config/useAnalyticsSources.js +17 -21
  293. package/dist/fields/config/useAnalyticsSources.js.map +1 -1
  294. package/dist/fields/config/useFilterCapabilities.d.ts +9 -6
  295. package/dist/fields/config/useFilterCapabilities.js +23 -15
  296. package/dist/fields/config/useFilterCapabilities.js.map +1 -1
  297. package/dist/fields/config/useFormString.js +12 -0
  298. package/dist/fields/config/useFormString.js.map +1 -0
  299. package/dist/fields/dateRange/field.js +7 -19
  300. package/dist/fields/dateRange/field.js.map +1 -1
  301. package/dist/fields/dateRange/types.d.ts +5 -1
  302. package/dist/fields/dateRange/ui.d.ts +3 -2
  303. package/dist/fields/dateRange/ui.js +57 -319
  304. package/dist/fields/dateRange/ui.js.map +1 -1
  305. package/dist/fields/documentScope.js +21 -0
  306. package/dist/fields/documentScope.js.map +1 -0
  307. package/dist/fields/emptyState.js +30 -26
  308. package/dist/fields/emptyState.js.map +1 -1
  309. package/dist/fields/factories.d.ts +35 -16
  310. package/dist/fields/factories.js +67 -38
  311. package/dist/fields/factories.js.map +1 -1
  312. package/dist/fields/format.d.ts +12 -3
  313. package/dist/fields/format.js +77 -13
  314. package/dist/fields/format.js.map +1 -1
  315. package/dist/fields/itemReport.js +45 -0
  316. package/dist/fields/itemReport.js.map +1 -0
  317. package/dist/fields/readForDocument.d.ts +79 -26
  318. package/dist/fields/readForDocument.js +450 -116
  319. package/dist/fields/readForDocument.js.map +1 -1
  320. package/dist/fields/stateKeys.js +20 -0
  321. package/dist/fields/stateKeys.js.map +1 -0
  322. package/dist/goals/GoalAmountField.d.ts +10 -0
  323. package/dist/goals/GoalAmountField.js +179 -0
  324. package/dist/goals/GoalAmountField.js.map +1 -0
  325. package/dist/goals/GoalSelectField.js +89 -40
  326. package/dist/goals/GoalSelectField.js.map +1 -1
  327. package/dist/goals/GoalSelectFieldServer.d.ts +13 -0
  328. package/dist/goals/GoalSelectFieldServer.js +21 -0
  329. package/dist/goals/GoalSelectFieldServer.js.map +1 -0
  330. package/dist/goals/amountField.d.ts +20 -0
  331. package/dist/goals/amountField.js +37 -0
  332. package/dist/goals/amountField.js.map +1 -0
  333. package/dist/goals/builtin.js +17 -0
  334. package/dist/goals/builtin.js.map +1 -0
  335. package/dist/goals/collection.d.ts +22 -0
  336. package/dist/goals/collection.js +143 -124
  337. package/dist/goals/collection.js.map +1 -1
  338. package/dist/goals/constants.d.ts +38 -0
  339. package/dist/goals/constants.js +49 -0
  340. package/dist/goals/constants.js.map +1 -0
  341. package/dist/goals/currency.d.ts +16 -0
  342. package/dist/goals/currency.js +46 -4
  343. package/dist/goals/currency.js.map +1 -1
  344. package/dist/goals/currencyOptions.js +70 -0
  345. package/dist/goals/currencyOptions.js.map +1 -0
  346. package/dist/goals/fetchGoals.d.ts +10 -0
  347. package/dist/goals/fetchGoals.js +12 -22
  348. package/dist/goals/fetchGoals.js.map +1 -1
  349. package/dist/goals/goalField.d.ts +4 -6
  350. package/dist/goals/goalField.js +9 -19
  351. package/dist/goals/goalField.js.map +1 -1
  352. package/dist/goals/goalsEndpoint.js +40 -38
  353. package/dist/goals/goalsEndpoint.js.map +1 -1
  354. package/dist/goals/items.js +35 -0
  355. package/dist/goals/items.js.map +1 -0
  356. package/dist/goals/latent.js +9 -0
  357. package/dist/goals/latent.js.map +1 -0
  358. package/dist/goals/linkFields.d.ts +35 -0
  359. package/dist/goals/linkFields.js +31 -0
  360. package/dist/goals/linkFields.js.map +1 -0
  361. package/dist/goals/match.d.ts +14 -0
  362. package/dist/goals/match.js +67 -46
  363. package/dist/goals/match.js.map +1 -1
  364. package/dist/goals/moneyFields.js +56 -0
  365. package/dist/goals/moneyFields.js.map +1 -0
  366. package/dist/goals/pathMatch.js +122 -0
  367. package/dist/goals/pathMatch.js.map +1 -0
  368. package/dist/goals/placeholder.js +12 -0
  369. package/dist/goals/placeholder.js.map +1 -0
  370. package/dist/goals/resolver.d.ts +3 -3
  371. package/dist/goals/resolver.js +155 -47
  372. package/dist/goals/resolver.js.map +1 -1
  373. package/dist/goals/serverRevenue.d.ts +60 -0
  374. package/dist/goals/serverRevenue.js +41 -0
  375. package/dist/goals/serverRevenue.js.map +1 -0
  376. package/dist/goals/trackGoalAction.d.ts +26 -25
  377. package/dist/goals/trackGoalAction.js +71 -66
  378. package/dist/goals/trackGoalAction.js.map +1 -1
  379. package/dist/goals/types.d.ts +13 -28
  380. package/dist/goals/types.js +1 -1
  381. package/dist/goals/types.js.map +1 -1
  382. package/dist/goals/useAnalyticsGoals.d.ts +6 -5
  383. package/dist/goals/useAnalyticsGoals.js +17 -18
  384. package/dist/goals/useAnalyticsGoals.js.map +1 -1
  385. package/dist/index.d.ts +68 -12
  386. package/dist/index.js +261 -192
  387. package/dist/index.js.map +1 -1
  388. package/dist/items/collectionIdType.js +20 -0
  389. package/dist/items/collectionIdType.js.map +1 -0
  390. package/dist/items/idType.js +31 -0
  391. package/dist/items/idType.js.map +1 -0
  392. package/dist/items/ref.js +73 -0
  393. package/dist/items/ref.js.map +1 -0
  394. package/dist/maintenance/apiTaskState.js +141 -0
  395. package/dist/maintenance/apiTaskState.js.map +1 -0
  396. package/dist/maintenance/heartbeat.js +51 -0
  397. package/dist/maintenance/heartbeat.js.map +1 -0
  398. package/dist/maintenance/lease.d.ts +1 -0
  399. package/dist/maintenance/lease.js +79 -0
  400. package/dist/maintenance/lease.js.map +1 -0
  401. package/dist/maintenance/taskSchedule.js +27 -0
  402. package/dist/maintenance/taskSchedule.js.map +1 -0
  403. package/dist/maintenance/underLease.js +35 -0
  404. package/dist/maintenance/underLease.js.map +1 -0
  405. package/dist/migrations/legacy.d.ts +54 -0
  406. package/dist/migrations/legacy.js +117 -0
  407. package/dist/migrations/legacy.js.map +1 -0
  408. package/dist/migrations/predefined/dropLegacyMongo.d.ts +11 -0
  409. package/dist/migrations/predefined/dropLegacyMongo.js +12 -0
  410. package/dist/migrations/predefined/dropLegacyMongo.js.map +1 -0
  411. package/dist/native/collections/aggregates.js +54 -0
  412. package/dist/native/collections/aggregates.js.map +1 -0
  413. package/dist/native/collections/hits.js +103 -0
  414. package/dist/native/collections/hits.js.map +1 -0
  415. package/dist/native/collections/slugs.d.ts +10 -0
  416. package/dist/native/collections/slugs.js +16 -0
  417. package/dist/native/collections/slugs.js.map +1 -0
  418. package/dist/native/collections/state.js +84 -0
  419. package/dist/native/collections/state.js.map +1 -0
  420. package/dist/native/collections/storeCollection.js +31 -0
  421. package/dist/native/collections/storeCollection.js.map +1 -0
  422. package/dist/native/engine/buckets.d.ts +1 -0
  423. package/dist/native/engine/buckets.js +53 -0
  424. package/dist/native/engine/buckets.js.map +1 -0
  425. package/dist/native/engine/capabilities.js +87 -0
  426. package/dist/native/engine/capabilities.js.map +1 -0
  427. package/dist/native/engine/cost.js +72 -0
  428. package/dist/native/engine/cost.js.map +1 -0
  429. package/dist/native/engine/days.d.ts +1 -0
  430. package/dist/native/engine/days.js +182 -0
  431. package/dist/native/engine/days.js.map +1 -0
  432. package/dist/native/engine/engine.d.ts +1 -0
  433. package/dist/native/engine/engine.js +1627 -0
  434. package/dist/native/engine/engine.js.map +1 -0
  435. package/dist/native/engine/instance.js +58 -0
  436. package/dist/native/engine/instance.js.map +1 -0
  437. package/dist/native/engine/maintenance.d.ts +1 -0
  438. package/dist/native/engine/maintenance.js +677 -0
  439. package/dist/native/engine/maintenance.js.map +1 -0
  440. package/dist/native/engine/merge.js +41 -0
  441. package/dist/native/engine/merge.js.map +1 -0
  442. package/dist/native/engine/nudge.js +26 -0
  443. package/dist/native/engine/nudge.js.map +1 -0
  444. package/dist/native/engine/planner.js +199 -0
  445. package/dist/native/engine/planner.js.map +1 -0
  446. package/dist/native/engine/rebuild.d.ts +22 -0
  447. package/dist/native/engine/rebuild.js +76 -0
  448. package/dist/native/engine/rebuild.js.map +1 -0
  449. package/dist/native/engine/recent.js +17 -0
  450. package/dist/native/engine/recent.js.map +1 -0
  451. package/dist/native/engine/salt.d.ts +1 -0
  452. package/dist/native/engine/salt.js +98 -0
  453. package/dist/native/engine/salt.js.map +1 -0
  454. package/dist/native/engine/siteHosts.d.ts +1 -0
  455. package/dist/native/engine/siteHosts.js +58 -0
  456. package/dist/native/engine/siteHosts.js.map +1 -0
  457. package/dist/native/engine/toHit.js +110 -0
  458. package/dist/native/engine/toHit.js.map +1 -0
  459. package/dist/native/engine/writeBuffer.d.ts +14 -0
  460. package/dist/native/engine/writeBuffer.js +317 -0
  461. package/dist/native/engine/writeBuffer.js.map +1 -0
  462. package/dist/native/geo/composeGeoResolvers.d.ts +1 -0
  463. package/dist/native/geo/composeGeoResolvers.js +5 -2
  464. package/dist/native/geo/composeGeoResolvers.js.map +1 -1
  465. package/dist/native/geo/geoResolver.d.ts +27 -2
  466. package/dist/native/geo/geoResolver.js +42 -6
  467. package/dist/native/geo/geoResolver.js.map +1 -1
  468. package/dist/native/geo/maxmindResolver.d.ts +8 -4
  469. package/dist/native/geo/maxmindResolver.js +20 -16
  470. package/dist/native/geo/maxmindResolver.js.map +1 -1
  471. package/dist/native/geo/resolveGeo.js +31 -0
  472. package/dist/native/geo/resolveGeo.js.map +1 -0
  473. package/dist/native/ingest/bots.d.ts +10 -0
  474. package/dist/native/ingest/bots.js +66 -0
  475. package/dist/native/ingest/bots.js.map +1 -0
  476. package/dist/native/ingest/browser.js +4 -6
  477. package/dist/native/ingest/browser.js.map +1 -1
  478. package/dist/native/ingest/clientIp.js +34 -8
  479. package/dist/native/ingest/clientIp.js.map +1 -1
  480. package/dist/native/ingest/device.js +4 -6
  481. package/dist/native/ingest/device.js.map +1 -1
  482. package/dist/native/ingest/endpoint.d.ts +1 -1
  483. package/dist/native/ingest/endpoint.js +185 -32
  484. package/dist/native/ingest/endpoint.js.map +1 -1
  485. package/dist/native/ingest/itemSignature.d.ts +26 -0
  486. package/dist/native/ingest/itemSignature.js +45 -0
  487. package/dist/native/ingest/itemSignature.js.map +1 -0
  488. package/dist/native/ingest/language.js +2 -3
  489. package/dist/native/ingest/language.js.map +1 -1
  490. package/dist/native/ingest/normalizeEvent.d.ts +70 -8
  491. package/dist/native/ingest/normalizeEvent.js +239 -60
  492. package/dist/native/ingest/normalizeEvent.js.map +1 -1
  493. package/dist/native/ingest/orderSignature.d.ts +13 -0
  494. package/dist/native/ingest/orderSignature.js +50 -0
  495. package/dist/native/ingest/orderSignature.js.map +1 -0
  496. package/dist/native/ingest/referrer.js +30 -32
  497. package/dist/native/ingest/referrer.js.map +1 -1
  498. package/dist/native/ingest/requestHost.js +44 -0
  499. package/dist/native/ingest/requestHost.js.map +1 -0
  500. package/dist/native/ingest/resolveHostname.d.ts +20 -0
  501. package/dist/native/ingest/resolveHostname.js +51 -0
  502. package/dist/native/ingest/resolveHostname.js.map +1 -0
  503. package/dist/native/ingest/revenue.d.ts +1 -0
  504. package/dist/native/ingest/revenue.js +121 -0
  505. package/dist/native/ingest/revenue.js.map +1 -0
  506. package/dist/native/ingest/route.d.ts +10 -0
  507. package/dist/native/ingest/route.js +85 -0
  508. package/dist/native/ingest/route.js.map +1 -0
  509. package/dist/native/ingest/serverTrack.d.ts +2 -10
  510. package/dist/native/ingest/serverTrack.js +188 -69
  511. package/dist/native/ingest/serverTrack.js.map +1 -1
  512. package/dist/native/ingest/signature.js +28 -0
  513. package/dist/native/ingest/signature.js.map +1 -0
  514. package/dist/native/ingest/source.d.ts +5 -2
  515. package/dist/native/ingest/source.js +163 -59
  516. package/dist/native/ingest/source.js.map +1 -1
  517. package/dist/native/ingest/utm.js +9 -9
  518. package/dist/native/ingest/utm.js.map +1 -1
  519. package/dist/native/ingest/validate.js +25 -13
  520. package/dist/native/ingest/validate.js.map +1 -1
  521. package/dist/native/ingest/visitorHash.js +6 -8
  522. package/dist/native/ingest/visitorHash.js.map +1 -1
  523. package/dist/native/nativeAdapter.d.ts +128 -9
  524. package/dist/native/nativeAdapter.js +396 -288
  525. package/dist/native/nativeAdapter.js.map +1 -1
  526. package/dist/native/rebuildDays.d.ts +12 -0
  527. package/dist/native/rebuildDays.js +16 -0
  528. package/dist/native/rebuildDays.js.map +1 -0
  529. package/dist/native/store/aggregate.js +450 -0
  530. package/dist/native/store/aggregate.js.map +1 -0
  531. package/dist/native/store/caps.d.ts +18 -0
  532. package/dist/native/store/caps.js +76 -0
  533. package/dist/native/store/caps.js.map +1 -0
  534. package/dist/native/store/chunks.js +34 -0
  535. package/dist/native/store/chunks.js.map +1 -0
  536. package/dist/native/store/columnValues.js +31 -0
  537. package/dist/native/store/columnValues.js.map +1 -0
  538. package/dist/native/store/dialect.js +106 -0
  539. package/dist/native/store/dialect.js.map +1 -0
  540. package/dist/native/store/eventStore.js +44 -0
  541. package/dist/native/store/eventStore.js.map +1 -0
  542. package/dist/native/store/hitRow.js +119 -0
  543. package/dist/native/store/hitRow.js.map +1 -0
  544. package/dist/native/store/hits.js +65 -0
  545. package/dist/native/store/hits.js.map +1 -0
  546. package/dist/native/store/ids.js +105 -0
  547. package/dist/native/store/ids.js.map +1 -0
  548. package/dist/native/store/mongo/aggregatePipelines.js +438 -0
  549. package/dist/native/store/mongo/aggregatePipelines.js.map +1 -0
  550. package/dist/native/store/mongo/mongoState.js +375 -0
  551. package/dist/native/store/mongo/mongoState.js.map +1 -0
  552. package/dist/native/store/mongo/mongoStore.js +618 -0
  553. package/dist/native/store/mongo/mongoStore.js.map +1 -0
  554. package/dist/native/store/mongo/pipelines.js +705 -0
  555. package/dist/native/store/mongo/pipelines.js.map +1 -0
  556. package/dist/native/store/mongo/results.js +20 -0
  557. package/dist/native/store/mongo/results.js.map +1 -0
  558. package/dist/native/store/parts.d.ts +1 -0
  559. package/dist/native/store/parts.js +101 -0
  560. package/dist/native/store/parts.js.map +1 -0
  561. package/dist/native/store/pattern.js +213 -0
  562. package/dist/native/store/pattern.js.map +1 -0
  563. package/dist/native/store/rawRead.d.ts +23 -0
  564. package/dist/native/store/rawRead.js +387 -0
  565. package/dist/native/store/rawRead.js.map +1 -0
  566. package/dist/native/store/reclassify.js +53 -0
  567. package/dist/native/store/reclassify.js.map +1 -0
  568. package/dist/native/store/sql/aggregateSql.js +349 -0
  569. package/dist/native/store/sql/aggregateSql.js.map +1 -0
  570. package/dist/native/store/sql/columns.js +49 -0
  571. package/dist/native/store/sql/columns.js.map +1 -0
  572. package/dist/native/store/sql/compile.js +668 -0
  573. package/dist/native/store/sql/compile.js.map +1 -0
  574. package/dist/native/store/sql/drivers.js +218 -0
  575. package/dist/native/store/sql/drivers.js.map +1 -0
  576. package/dist/native/store/sql/executor.js +132 -0
  577. package/dist/native/store/sql/executor.js.map +1 -0
  578. package/dist/native/store/sql/fragment.js +104 -0
  579. package/dist/native/store/sql/fragment.js.map +1 -0
  580. package/dist/native/store/sql/maintenanceSql.js +59 -0
  581. package/dist/native/store/sql/maintenanceSql.js.map +1 -0
  582. package/dist/native/store/sql/ownConnection.js +107 -0
  583. package/dist/native/store/sql/ownConnection.js.map +1 -0
  584. package/dist/native/store/sql/poolShare.js +101 -0
  585. package/dist/native/store/sql/poolShare.js.map +1 -0
  586. package/dist/native/store/sql/sqlState.js +325 -0
  587. package/dist/native/store/sql/sqlState.js.map +1 -0
  588. package/dist/native/store/sql/sqlStore.js +355 -0
  589. package/dist/native/store/sql/sqlStore.js.map +1 -0
  590. package/dist/native/store/sql/sqliteThread.d.ts +9 -0
  591. package/dist/native/store/sql/sqliteThread.js +314 -0
  592. package/dist/native/store/sql/sqliteThread.js.map +1 -0
  593. package/dist/native/store/sql/sqliteWorker.js +327 -0
  594. package/dist/native/store/sql/sqliteWorker.js.map +1 -0
  595. package/dist/native/store/sql/sqliteWorkerSource.js +347 -0
  596. package/dist/native/store/sql/sqliteWorkerSource.js.map +1 -0
  597. package/dist/native/store/state.js +151 -0
  598. package/dist/native/store/state.js.map +1 -0
  599. package/dist/native/store/stateStore.js +29 -0
  600. package/dist/native/store/stateStore.js.map +1 -0
  601. package/dist/native/store/types.d.ts +15 -0
  602. package/dist/native/store/types.js +10 -0
  603. package/dist/native/store/types.js.map +1 -0
  604. package/dist/native/tasks/maintainTask.d.ts +19 -0
  605. package/dist/native/tasks/maintainTask.js +57 -0
  606. package/dist/native/tasks/maintainTask.js.map +1 -0
  607. package/dist/net/guardedFetch.d.ts +32 -0
  608. package/dist/net/guardedFetch.js +220 -0
  609. package/dist/net/guardedFetch.js.map +1 -0
  610. package/dist/net/origin.js +40 -0
  611. package/dist/net/origin.js.map +1 -0
  612. package/dist/net/platform.d.ts +9 -0
  613. package/dist/net/platform.js +35 -0
  614. package/dist/net/platform.js.map +1 -0
  615. package/dist/plugin/adminDependencies.js +34 -0
  616. package/dist/plugin/adminDependencies.js.map +1 -0
  617. package/dist/plugin/apiPath.js +23 -0
  618. package/dist/plugin/apiPath.js.map +1 -0
  619. package/dist/plugin/boundDocument.js +58 -0
  620. package/dist/plugin/boundDocument.js.map +1 -0
  621. package/dist/plugin/buildPhase.js +10 -0
  622. package/dist/plugin/buildPhase.js.map +1 -0
  623. package/dist/plugin/collectionChecks.js +232 -0
  624. package/dist/plugin/collectionChecks.js.map +1 -0
  625. package/dist/plugin/collectionFields.d.ts +13 -0
  626. package/dist/plugin/collectionFields.js +22 -0
  627. package/dist/plugin/collectionFields.js.map +1 -0
  628. package/dist/plugin/createRuntime.js +346 -0
  629. package/dist/plugin/createRuntime.js.map +1 -0
  630. package/dist/plugin/destroy.js +58 -0
  631. package/dist/plugin/destroy.js.map +1 -0
  632. package/dist/plugin/documentEndpoint.js +105 -71
  633. package/dist/plugin/documentEndpoint.js.map +1 -1
  634. package/dist/plugin/documentScopes.js +37 -0
  635. package/dist/plugin/documentScopes.js.map +1 -0
  636. package/dist/plugin/encrypted.js +25 -0
  637. package/dist/plugin/encrypted.js.map +1 -0
  638. package/dist/plugin/errors.d.ts +24 -0
  639. package/dist/plugin/errors.js +86 -0
  640. package/dist/plugin/errors.js.map +1 -0
  641. package/dist/plugin/flagsEndpoint.js +41 -0
  642. package/dist/plugin/flagsEndpoint.js.map +1 -0
  643. package/dist/plugin/goalHint.js +22 -11
  644. package/dist/plugin/goalHint.js.map +1 -1
  645. package/dist/plugin/itemLabels.js +114 -0
  646. package/dist/plugin/itemLabels.js.map +1 -0
  647. package/dist/plugin/keepAlive.js +48 -0
  648. package/dist/plugin/keepAlive.js.map +1 -0
  649. package/dist/plugin/peerImportError.js +3 -6
  650. package/dist/plugin/peerImportError.js.map +1 -1
  651. package/dist/plugin/peers.js +64 -0
  652. package/dist/plugin/peers.js.map +1 -0
  653. package/dist/plugin/pluginCollections.js +161 -0
  654. package/dist/plugin/pluginCollections.js.map +1 -0
  655. package/dist/plugin/queryEndpoint.js +80 -51
  656. package/dist/plugin/queryEndpoint.js.map +1 -1
  657. package/dist/plugin/queryParams.js +7 -0
  658. package/dist/plugin/queryParams.js.map +1 -0
  659. package/dist/plugin/readContextForRequest.d.ts +11 -0
  660. package/dist/plugin/readContextForRequest.js +79 -32
  661. package/dist/plugin/readContextForRequest.js.map +1 -1
  662. package/dist/plugin/readFailure.js +22 -0
  663. package/dist/plugin/readFailure.js.map +1 -0
  664. package/dist/plugin/readableProviders.js +67 -0
  665. package/dist/plugin/readableProviders.js.map +1 -0
  666. package/dist/plugin/realtimeEndpoint.js +79 -34
  667. package/dist/plugin/realtimeEndpoint.js.map +1 -1
  668. package/dist/plugin/refreshEndpoint.js +138 -0
  669. package/dist/plugin/refreshEndpoint.js.map +1 -0
  670. package/dist/plugin/relabelFields.js +36 -0
  671. package/dist/plugin/relabelFields.js.map +1 -0
  672. package/dist/plugin/requestMemo.js +35 -0
  673. package/dist/plugin/requestMemo.js.map +1 -0
  674. package/dist/plugin/routeChecks.js +39 -0
  675. package/dist/plugin/routeChecks.js.map +1 -0
  676. package/dist/plugin/routes.d.ts +53 -0
  677. package/dist/plugin/routes.js +92 -0
  678. package/dist/plugin/routes.js.map +1 -0
  679. package/dist/plugin/runtime.d.ts +1 -1
  680. package/dist/plugin/runtime.js +235 -29
  681. package/dist/plugin/runtime.js.map +1 -1
  682. package/dist/plugin/schemaOnly.js +61 -0
  683. package/dist/plugin/schemaOnly.js.map +1 -0
  684. package/dist/plugin/scopeChange.js +23 -0
  685. package/dist/plugin/scopeChange.js.map +1 -0
  686. package/dist/plugin/scopeFieldBoot.js +4 -4
  687. package/dist/plugin/scopeFieldBoot.js.map +1 -1
  688. package/dist/plugin/scopeToken.js +33 -0
  689. package/dist/plugin/scopeToken.js.map +1 -0
  690. package/dist/plugin/sourcesEndpoint.js +50 -23
  691. package/dist/plugin/sourcesEndpoint.js.map +1 -1
  692. package/dist/plugin/unbundledLanguages.js +25 -0
  693. package/dist/plugin/unbundledLanguages.js.map +1 -0
  694. package/dist/plugin/walkFields.js +24 -0
  695. package/dist/plugin/walkFields.js.map +1 -0
  696. package/dist/plugin/warmTask.js +0 -0
  697. package/dist/plugin/warmTask.js.map +1 -1
  698. package/dist/providers/ProvidersListNotice.d.ts +11 -0
  699. package/dist/providers/ProvidersListNotice.js +36 -0
  700. package/dist/providers/ProvidersListNotice.js.map +1 -0
  701. package/dist/providers/access.d.ts +1 -0
  702. package/dist/providers/access.js +35 -26
  703. package/dist/providers/access.js.map +1 -1
  704. package/dist/providers/adapterPool.js +121 -0
  705. package/dist/providers/adapterPool.js.map +1 -0
  706. package/dist/providers/collection.d.ts +63 -0
  707. package/dist/providers/collection.js +369 -150
  708. package/dist/providers/collection.js.map +1 -1
  709. package/dist/providers/factory.d.ts +84 -0
  710. package/dist/providers/factory.js +84 -25
  711. package/dist/providers/factory.js.map +1 -1
  712. package/dist/providers/hosts.d.ts +25 -0
  713. package/dist/providers/hosts.js +128 -0
  714. package/dist/providers/hosts.js.map +1 -0
  715. package/dist/providers/probe.d.ts +1 -0
  716. package/dist/providers/probe.js +105 -0
  717. package/dist/providers/probe.js.map +1 -0
  718. package/dist/providers/refresh.d.ts +18 -0
  719. package/dist/providers/refresh.js +49 -0
  720. package/dist/providers/refresh.js.map +1 -0
  721. package/dist/providers/registry.js +329 -0
  722. package/dist/providers/registry.js.map +1 -0
  723. package/dist/providers/resolver.js +26 -88
  724. package/dist/providers/resolver.js.map +1 -1
  725. package/dist/providers/retarget.js +45 -0
  726. package/dist/providers/retarget.js.map +1 -0
  727. package/dist/providers/scopeUnique.js +41 -0
  728. package/dist/providers/scopeUnique.js.map +1 -0
  729. package/dist/providers/secrets.d.ts +26 -0
  730. package/dist/providers/secrets.js +61 -4
  731. package/dist/providers/secrets.js.map +1 -1
  732. package/dist/providers/stampScope.js +9 -6
  733. package/dist/providers/stampScope.js.map +1 -1
  734. package/dist/query/dates.js +10 -12
  735. package/dist/query/dates.js.map +1 -1
  736. package/dist/query/errors.d.ts +6 -13
  737. package/dist/query/fetchQuery.d.ts +36 -23
  738. package/dist/query/fetchQuery.js +96 -89
  739. package/dist/query/fetchQuery.js.map +1 -1
  740. package/dist/query/limits.js +8 -0
  741. package/dist/query/limits.js.map +1 -0
  742. package/dist/query/parse.d.ts +8 -2
  743. package/dist/query/parse.js +155 -108
  744. package/dist/query/parse.js.map +1 -1
  745. package/dist/query/response.d.ts +23 -3
  746. package/dist/query/response.js +12 -5
  747. package/dist/query/response.js.map +1 -1
  748. package/dist/react/AnalyticsProvider.d.ts +42 -20
  749. package/dist/react/AnalyticsProvider.js +24 -22
  750. package/dist/react/AnalyticsProvider.js.map +1 -1
  751. package/dist/react/TrackerBoot.js +15 -9
  752. package/dist/react/TrackerBoot.js.map +1 -1
  753. package/dist/react/useAnalytics.d.ts +2 -8
  754. package/dist/react/useAnalytics.js +31 -13
  755. package/dist/react/useAnalytics.js.map +1 -1
  756. package/dist/routes/captureRoute.d.ts +28 -0
  757. package/dist/routes/captureRoute.js +67 -0
  758. package/dist/routes/captureRoute.js.map +1 -0
  759. package/dist/routes/ingestRoute.d.ts +17 -0
  760. package/dist/routes/ingestRoute.js +17 -0
  761. package/dist/routes/ingestRoute.js.map +1 -0
  762. package/dist/site/AnalyticsScripts.d.ts +35 -0
  763. package/dist/site/AnalyticsScripts.js +44 -0
  764. package/dist/site/AnalyticsScripts.js.map +1 -0
  765. package/dist/site/getTrackerConfig.d.ts +15 -0
  766. package/dist/site/getTrackerConfig.js +43 -0
  767. package/dist/site/getTrackerConfig.js.map +1 -0
  768. package/dist/surfacing/afterRead.d.ts +37 -0
  769. package/dist/surfacing/bounded.js +38 -0
  770. package/dist/surfacing/bounded.js.map +1 -0
  771. package/dist/surfacing/breaker.js +107 -0
  772. package/dist/surfacing/breaker.js.map +1 -0
  773. package/dist/surfacing/cacheCollection.d.ts +8 -0
  774. package/dist/surfacing/cacheCollection.js +71 -0
  775. package/dist/surfacing/cacheCollection.js.map +1 -0
  776. package/dist/surfacing/cacheStore.d.ts +71 -1
  777. package/dist/surfacing/cacheStore.js +16 -37
  778. package/dist/surfacing/cacheStore.js.map +1 -1
  779. package/dist/surfacing/cacheSweep.d.ts +1 -0
  780. package/dist/surfacing/cacheSweep.js +59 -0
  781. package/dist/surfacing/cacheSweep.js.map +1 -0
  782. package/dist/surfacing/classifyError.js +282 -0
  783. package/dist/surfacing/classifyError.js.map +1 -0
  784. package/dist/surfacing/coalesce.js +2 -1
  785. package/dist/surfacing/coalesce.js.map +1 -1
  786. package/dist/surfacing/coldBudget.js +60 -0
  787. package/dist/surfacing/coldBudget.js.map +1 -0
  788. package/dist/surfacing/collectionCacheStore.js +183 -0
  789. package/dist/surfacing/collectionCacheStore.js.map +1 -0
  790. package/dist/surfacing/engine.d.ts +1 -1
  791. package/dist/surfacing/engine.js +514 -71
  792. package/dist/surfacing/engine.js.map +1 -1
  793. package/dist/surfacing/epoch.d.ts +1 -0
  794. package/dist/surfacing/epoch.js +116 -0
  795. package/dist/surfacing/epoch.js.map +1 -0
  796. package/dist/surfacing/lanes.d.ts +1 -0
  797. package/dist/surfacing/lanes.js +297 -0
  798. package/dist/surfacing/lanes.js.map +1 -0
  799. package/dist/surfacing/memo.js +40 -0
  800. package/dist/surfacing/memo.js.map +1 -0
  801. package/dist/surfacing/rateLimiter.d.ts +1 -0
  802. package/dist/surfacing/rateLimiter.js +69 -94
  803. package/dist/surfacing/rateLimiter.js.map +1 -1
  804. package/dist/surfacing/rebucket.js +178 -0
  805. package/dist/surfacing/rebucket.js.map +1 -0
  806. package/dist/surfacing/recipe.js +28 -0
  807. package/dist/surfacing/recipe.js.map +1 -0
  808. package/dist/surfacing/shape.js +22 -0
  809. package/dist/surfacing/shape.js.map +1 -0
  810. package/dist/surfacing/todaySplit.js +119 -0
  811. package/dist/surfacing/todaySplit.js.map +1 -0
  812. package/dist/sync/collection.d.ts +8 -0
  813. package/dist/sync/collection.js +30 -18
  814. package/dist/sync/collection.js.map +1 -1
  815. package/dist/sync/rekeyDurations.js +70 -0
  816. package/dist/sync/rekeyDurations.js.map +1 -0
  817. package/dist/sync/syncTask.js +222 -109
  818. package/dist/sync/syncTask.js.map +1 -1
  819. package/dist/testing/memoryAdapter.d.ts +6 -3
  820. package/dist/testing/memoryAdapter.js +12 -10
  821. package/dist/testing/memoryAdapter.js.map +1 -1
  822. package/dist/testing/settle.d.ts +11 -0
  823. package/dist/testing/settle.js +19 -0
  824. package/dist/testing/settle.js.map +1 -0
  825. package/dist/timeframe/calendar.js +65 -0
  826. package/dist/timeframe/calendar.js.map +1 -0
  827. package/dist/timeframe/comparison.js +46 -0
  828. package/dist/timeframe/comparison.js.map +1 -0
  829. package/dist/timeframe/presets.d.ts +1 -1
  830. package/dist/timeframe/presets.js +5 -5
  831. package/dist/timeframe/presets.js.map +1 -1
  832. package/dist/timeframe/reportingTimezone.d.ts +1 -0
  833. package/dist/timeframe/reportingTimezone.js +64 -0
  834. package/dist/timeframe/reportingTimezone.js.map +1 -0
  835. package/dist/timeframe/tz.js +55 -39
  836. package/dist/timeframe/tz.js.map +1 -1
  837. package/dist/tracker/autoCapture.js +125 -38
  838. package/dist/tracker/autoCapture.js.map +1 -1
  839. package/dist/tracker/campaign.js +52 -0
  840. package/dist/tracker/campaign.js.map +1 -0
  841. package/dist/tracker/config.d.ts +174 -0
  842. package/dist/tracker/config.js +25 -0
  843. package/dist/tracker/config.js.map +1 -0
  844. package/dist/tracker/createTracker.d.ts +5 -10
  845. package/dist/tracker/createTracker.js +434 -91
  846. package/dist/tracker/createTracker.js.map +1 -1
  847. package/dist/tracker/digest.js +28 -0
  848. package/dist/tracker/digest.js.map +1 -0
  849. package/dist/tracker/engagement.js +100 -0
  850. package/dist/tracker/engagement.js.map +1 -0
  851. package/dist/tracker/events.js +37 -0
  852. package/dist/tracker/events.js.map +1 -0
  853. package/dist/tracker/exclusion.d.ts +8 -0
  854. package/dist/tracker/exclusion.js +82 -0
  855. package/dist/tracker/exclusion.js.map +1 -0
  856. package/dist/tracker/gate.d.ts +8 -0
  857. package/dist/tracker/gate.js +244 -0
  858. package/dist/tracker/gate.js.map +1 -0
  859. package/dist/tracker/initTracker.d.ts +5 -8
  860. package/dist/tracker/initTracker.js +42 -14
  861. package/dist/tracker/initTracker.js.map +1 -1
  862. package/dist/tracker/itemCapture.js +224 -0
  863. package/dist/tracker/itemCapture.js.map +1 -0
  864. package/dist/tracker/loadScript.js +23 -15
  865. package/dist/tracker/loadScript.js.map +1 -1
  866. package/dist/tracker/pageTracking.js +6 -6
  867. package/dist/tracker/pageTracking.js.map +1 -1
  868. package/dist/tracker/registry.js +129 -30
  869. package/dist/tracker/registry.js.map +1 -1
  870. package/dist/tracker/sinks/createSink.js +60 -0
  871. package/dist/tracker/sinks/createSink.js.map +1 -0
  872. package/dist/tracker/sinks/ga4.js +97 -17
  873. package/dist/tracker/sinks/ga4.js.map +1 -1
  874. package/dist/tracker/sinks/native.js +21 -42
  875. package/dist/tracker/sinks/native.js.map +1 -1
  876. package/dist/tracker/sinks/plausible.js +36 -18
  877. package/dist/tracker/sinks/plausible.js.map +1 -1
  878. package/dist/tracker/sinks/posthog.js +145 -9
  879. package/dist/tracker/sinks/posthog.js.map +1 -1
  880. package/dist/tracker/sinks/umami.js +18 -10
  881. package/dist/tracker/sinks/umami.js.map +1 -1
  882. package/dist/tracker/sinks/vendor.js +54 -22
  883. package/dist/tracker/sinks/vendor.js.map +1 -1
  884. package/dist/tracker/skip.js +81 -0
  885. package/dist/tracker/skip.js.map +1 -0
  886. package/dist/tracker/storage.js +23 -0
  887. package/dist/tracker/storage.js.map +1 -0
  888. package/dist/tracker/transport.js +2 -5
  889. package/dist/tracker/transport.js.map +1 -1
  890. package/dist/tracker/types.d.ts +99 -49
  891. package/dist/tracker/window.js +7 -0
  892. package/dist/tracker/window.js.map +1 -0
  893. package/dist/translations/ar.js +255 -74
  894. package/dist/translations/ar.js.map +1 -1
  895. package/dist/translations/de.js +243 -71
  896. package/dist/translations/de.js.map +1 -1
  897. package/dist/translations/en.js +238 -70
  898. package/dist/translations/en.js.map +1 -1
  899. package/dist/translations/es.js +246 -71
  900. package/dist/translations/es.js.map +1 -1
  901. package/dist/translations/fr.js +250 -75
  902. package/dist/translations/fr.js.map +1 -1
  903. package/dist/translations/id.js +241 -70
  904. package/dist/translations/id.js.map +1 -1
  905. package/dist/translations/index.d.ts +1 -1
  906. package/dist/translations/index.js +5 -7
  907. package/dist/translations/index.js.map +1 -1
  908. package/dist/translations/intl.js +71 -0
  909. package/dist/translations/intl.js.map +1 -0
  910. package/dist/translations/keys.d.ts +214 -17
  911. package/dist/translations/keys.js +219 -17
  912. package/dist/translations/keys.js.map +1 -1
  913. package/dist/translations/ko.js +243 -72
  914. package/dist/translations/ko.js.map +1 -1
  915. package/dist/translations/labelMap.d.ts +10 -0
  916. package/dist/translations/labelMap.js +22 -0
  917. package/dist/translations/labelMap.js.map +1 -0
  918. package/dist/translations/metricKeys.js +10 -2
  919. package/dist/translations/metricKeys.js.map +1 -1
  920. package/dist/translations/parts.js +20 -0
  921. package/dist/translations/parts.js.map +1 -0
  922. package/dist/translations/plural.js +61 -0
  923. package/dist/translations/plural.js.map +1 -0
  924. package/dist/translations/pt.js +255 -80
  925. package/dist/translations/pt.js.map +1 -1
  926. package/dist/translations/ru.js +246 -69
  927. package/dist/translations/ru.js.map +1 -1
  928. package/dist/translations/server.d.ts +1 -0
  929. package/dist/translations/server.js +2 -3
  930. package/dist/translations/server.js.map +1 -1
  931. package/dist/translations/staticLabel.js +69 -0
  932. package/dist/translations/staticLabel.js.map +1 -0
  933. package/dist/translations/uk.js +246 -69
  934. package/dist/translations/uk.js.map +1 -1
  935. package/dist/translations/zh.js +241 -70
  936. package/dist/translations/zh.js.map +1 -1
  937. package/dist/ui/RangePicker.js +110 -0
  938. package/dist/ui/RangePicker.js.map +1 -0
  939. package/dist/ui/analytics.css +1667 -0
  940. package/dist/ui/calendarDays.js +27 -0
  941. package/dist/ui/calendarDays.js.map +1 -0
  942. package/dist/ui/classNames.js +7 -0
  943. package/dist/ui/classNames.js.map +1 -0
  944. package/dist/ui/components/Card.d.ts +28 -0
  945. package/dist/ui/components/Card.js +21 -0
  946. package/dist/ui/components/Card.js.map +1 -0
  947. package/dist/ui/components/ChartDataTable.d.ts +41 -0
  948. package/dist/ui/components/ChartDataTable.js +48 -0
  949. package/dist/ui/components/ChartDataTable.js.map +1 -0
  950. package/dist/ui/components/ChoiceMenu.js +48 -0
  951. package/dist/ui/components/ChoiceMenu.js.map +1 -0
  952. package/dist/ui/components/DataTable.d.ts +82 -0
  953. package/dist/ui/components/DataTable.js +214 -0
  954. package/dist/ui/components/DataTable.js.map +1 -0
  955. package/dist/ui/components/LabeledSelect.js +62 -0
  956. package/dist/ui/components/LabeledSelect.js.map +1 -0
  957. package/dist/ui/components/LiveAnnouncement.js +21 -0
  958. package/dist/ui/components/LiveAnnouncement.js.map +1 -0
  959. package/dist/ui/components/MetricCard.d.ts +38 -0
  960. package/dist/ui/components/MetricCard.js +39 -0
  961. package/dist/ui/components/MetricCard.js.map +1 -0
  962. package/dist/ui/components/NoValue.js +22 -0
  963. package/dist/ui/components/NoValue.js.map +1 -0
  964. package/dist/ui/components/ReadState.js +27 -0
  965. package/dist/ui/components/ReadState.js.map +1 -0
  966. package/dist/ui/components/RefreshButton.js +25 -0
  967. package/dist/ui/components/RefreshButton.js.map +1 -0
  968. package/dist/ui/components/SourcesNoticeBanner.js +20 -0
  969. package/dist/ui/components/SourcesNoticeBanner.js.map +1 -0
  970. package/dist/ui/cssVars.js +7 -0
  971. package/dist/ui/cssVars.js.map +1 -0
  972. package/dist/ui/data/WithScopeToken.d.ts +20 -0
  973. package/dist/ui/data/WithScopeToken.js +20 -0
  974. package/dist/ui/data/WithScopeToken.js.map +1 -0
  975. package/dist/ui/data/clientFieldProps.js +16 -0
  976. package/dist/ui/data/clientFieldProps.js.map +1 -0
  977. package/dist/ui/data/request.d.ts +46 -0
  978. package/dist/ui/data/request.js +119 -0
  979. package/dist/ui/data/request.js.map +1 -0
  980. package/dist/ui/data/scopeTokenContext.js +18 -0
  981. package/dist/ui/data/scopeTokenContext.js.map +1 -0
  982. package/dist/ui/data/sharedCache.js +48 -0
  983. package/dist/ui/data/sharedCache.js.map +1 -0
  984. package/dist/ui/data/useRequest.d.ts +19 -0
  985. package/dist/ui/data/useRequest.js +123 -0
  986. package/dist/ui/data/useRequest.js.map +1 -0
  987. package/dist/ui/data/useRequestScope.js +25 -0
  988. package/dist/ui/data/useRequestScope.js.map +1 -0
  989. package/dist/ui/hooks/useDirection.js +47 -0
  990. package/dist/ui/hooks/useDirection.js.map +1 -0
  991. package/dist/ui/hooks/useDismissOnEscape.js +25 -0
  992. package/dist/ui/hooks/useDismissOnEscape.js.map +1 -0
  993. package/dist/ui/hooks/useLiveAnnouncement.js +57 -0
  994. package/dist/ui/hooks/useLiveAnnouncement.js.map +1 -0
  995. package/dist/ui/hooks/useRealtimePoll.js +112 -0
  996. package/dist/ui/hooks/useRealtimePoll.js.map +1 -0
  997. package/dist/ui/readState.js +19 -0
  998. package/dist/ui/readState.js.map +1 -0
  999. package/dist/ui/rows/toDisplayRows.js +49 -0
  1000. package/dist/ui/rows/toDisplayRows.js.map +1 -0
  1001. package/dist/ui/viewerClock.js +7 -0
  1002. package/dist/ui/viewerClock.js.map +1 -0
  1003. package/dist/view/AnalyticsNavLink.d.ts +5 -3
  1004. package/dist/view/AnalyticsNavLink.js +12 -8
  1005. package/dist/view/AnalyticsNavLink.js.map +1 -1
  1006. package/dist/view/AnalyticsView.d.ts +9 -10
  1007. package/dist/view/AnalyticsView.js +47 -19
  1008. package/dist/view/AnalyticsView.js.map +1 -1
  1009. package/dist/view/AnalyticsViewClient.d.ts +4 -7
  1010. package/dist/view/AnalyticsViewClient.js +15 -185
  1011. package/dist/view/AnalyticsViewClient.js.map +1 -1
  1012. package/dist/view/CountryFlag.d.ts +27 -0
  1013. package/dist/view/CountryFlag.js +44 -0
  1014. package/dist/view/CountryFlag.js.map +1 -0
  1015. package/dist/view/DocumentTitle.js +27 -0
  1016. package/dist/view/DocumentTitle.js.map +1 -0
  1017. package/dist/view/ViewRoot.d.ts +21 -0
  1018. package/dist/view/ViewRoot.js +155 -0
  1019. package/dist/view/ViewRoot.js.map +1 -0
  1020. package/dist/view/ViewSections.d.ts +38 -0
  1021. package/dist/view/ViewSections.js +190 -0
  1022. package/dist/view/ViewSections.js.map +1 -0
  1023. package/dist/view/authRedirect.js +2 -4
  1024. package/dist/view/authRedirect.js.map +1 -1
  1025. package/dist/view/consentShare.js +15 -0
  1026. package/dist/view/consentShare.js.map +1 -0
  1027. package/dist/view/conversionRate.js +9 -7
  1028. package/dist/view/conversionRate.js.map +1 -1
  1029. package/dist/view/dayRange.js +6 -10
  1030. package/dist/view/dayRange.js.map +1 -1
  1031. package/dist/view/exclusionLink.d.ts +27 -0
  1032. package/dist/view/exclusionLink.js +46 -0
  1033. package/dist/view/exclusionLink.js.map +1 -0
  1034. package/dist/view/flagSrc.js +14 -0
  1035. package/dist/view/flagSrc.js.map +1 -0
  1036. package/dist/view/gating.d.ts +15 -1
  1037. package/dist/view/gating.js +67 -32
  1038. package/dist/view/gating.js.map +1 -1
  1039. package/dist/view/hostCountryFlag.js +41 -0
  1040. package/dist/view/hostCountryFlag.js.map +1 -0
  1041. package/dist/view/labels.js +113 -16
  1042. package/dist/view/labels.js.map +1 -1
  1043. package/dist/view/metricAliases.js +10 -0
  1044. package/dist/view/metricAliases.js.map +1 -0
  1045. package/dist/view/navLabel.js +15 -0
  1046. package/dist/view/navLabel.js.map +1 -0
  1047. package/dist/view/registerView.js +13 -11
  1048. package/dist/view/registerView.js.map +1 -1
  1049. package/dist/view/scopeLabel.js +21 -0
  1050. package/dist/view/scopeLabel.js.map +1 -0
  1051. package/dist/view/sections/Breakdowns.js +195 -132
  1052. package/dist/view/sections/Breakdowns.js.map +1 -1
  1053. package/dist/view/sections/EmptyStates.js +120 -32
  1054. package/dist/view/sections/EmptyStates.js.map +1 -1
  1055. package/dist/view/sections/ExcludeBrowser.js +188 -0
  1056. package/dist/view/sections/ExcludeBrowser.js.map +1 -0
  1057. package/dist/view/sections/FilterChips.js +127 -27
  1058. package/dist/view/sections/FilterChips.js.map +1 -1
  1059. package/dist/view/sections/GoalsPanel.js +68 -60
  1060. package/dist/view/sections/GoalsPanel.js.map +1 -1
  1061. package/dist/view/sections/OverviewCards.js +42 -36
  1062. package/dist/view/sections/OverviewCards.js.map +1 -1
  1063. package/dist/view/sections/RealtimeStrip.js +70 -59
  1064. package/dist/view/sections/RealtimeStrip.js.map +1 -1
  1065. package/dist/view/sections/SectionBoundary.js +34 -0
  1066. package/dist/view/sections/SectionBoundary.js.map +1 -0
  1067. package/dist/view/sections/Toolbar.d.ts +11 -0
  1068. package/dist/view/sections/Toolbar.js +181 -122
  1069. package/dist/view/sections/Toolbar.js.map +1 -1
  1070. package/dist/view/sections/Trend.js +176 -76
  1071. package/dist/view/sections/Trend.js.map +1 -1
  1072. package/dist/view/state.d.ts +42 -0
  1073. package/dist/view/state.js +93 -54
  1074. package/dist/view/state.js.map +1 -1
  1075. package/dist/view/useViewClock.js +31 -0
  1076. package/dist/view/useViewClock.js.map +1 -0
  1077. package/dist/view/useViewQueries.d.ts +21 -0
  1078. package/dist/view/useViewQueries.js +45 -77
  1079. package/dist/view/useViewQueries.js.map +1 -1
  1080. package/dist/view/useViewState.js +42 -0
  1081. package/dist/view/useViewState.js.map +1 -0
  1082. package/dist/view/useViewUrl.js +52 -0
  1083. package/dist/view/useViewUrl.js.map +1 -0
  1084. package/dist/view/viewBody.js +30 -0
  1085. package/dist/view/viewBody.js.map +1 -0
  1086. package/dist/view/viewContext.d.ts +81 -0
  1087. package/dist/view/viewContext.js +49 -0
  1088. package/dist/view/viewContext.js.map +1 -0
  1089. package/dist/view/viewProps.d.ts +65 -8
  1090. package/dist/view/viewProps.js +123 -36
  1091. package/dist/view/viewProps.js.map +1 -1
  1092. package/dist/widgets/AnalyticsBreakdownWidget.d.ts +7 -3
  1093. package/dist/widgets/AnalyticsBreakdownWidget.js +144 -118
  1094. package/dist/widgets/AnalyticsBreakdownWidget.js.map +1 -1
  1095. package/dist/widgets/AnalyticsGoalsWidget.d.ts +6 -7
  1096. package/dist/widgets/AnalyticsGoalsWidget.js +126 -167
  1097. package/dist/widgets/AnalyticsGoalsWidget.js.map +1 -1
  1098. package/dist/widgets/AnalyticsMetricWidget.d.ts +7 -3
  1099. package/dist/widgets/AnalyticsMetricWidget.js +81 -106
  1100. package/dist/widgets/AnalyticsMetricWidget.js.map +1 -1
  1101. package/dist/widgets/AnalyticsRealtimeWidget.d.ts +7 -3
  1102. package/dist/widgets/AnalyticsRealtimeWidget.js +81 -63
  1103. package/dist/widgets/AnalyticsRealtimeWidget.js.map +1 -1
  1104. package/dist/widgets/AnalyticsTrendWidget.d.ts +7 -3
  1105. package/dist/widgets/AnalyticsTrendWidget.js +130 -123
  1106. package/dist/widgets/AnalyticsTrendWidget.js.map +1 -1
  1107. package/dist/widgets/ComparisonDelta.js +33 -42
  1108. package/dist/widgets/ComparisonDelta.js.map +1 -1
  1109. package/dist/widgets/RealtimeCounter.d.ts +24 -4
  1110. package/dist/widgets/RealtimeCounter.js +90 -71
  1111. package/dist/widgets/RealtimeCounter.js.map +1 -1
  1112. package/dist/widgets/WidgetCard.d.ts +80 -0
  1113. package/dist/widgets/WidgetCard.js +99 -0
  1114. package/dist/widgets/WidgetCard.js.map +1 -0
  1115. package/dist/widgets/WidgetFrame.js +42 -0
  1116. package/dist/widgets/WidgetFrame.js.map +1 -0
  1117. package/dist/widgets/WidgetShimmer.d.ts +55 -0
  1118. package/dist/widgets/WidgetShimmer.js +86 -0
  1119. package/dist/widgets/WidgetShimmer.js.map +1 -0
  1120. package/dist/widgets/breakdownTypes.js +18 -2
  1121. package/dist/widgets/breakdownTypes.js.map +1 -1
  1122. package/dist/widgets/customWidget.d.ts +5 -1
  1123. package/dist/widgets/customWidget.js +6 -7
  1124. package/dist/widgets/customWidget.js.map +1 -1
  1125. package/dist/widgets/defaultLayout.d.ts +26 -0
  1126. package/dist/widgets/defaultLayout.js +51 -0
  1127. package/dist/widgets/defaultLayout.js.map +1 -0
  1128. package/dist/widgets/defaults.d.ts +4 -7
  1129. package/dist/widgets/defaults.js +12 -7
  1130. package/dist/widgets/defaults.js.map +1 -1
  1131. package/dist/widgets/fieldRows.js +14 -0
  1132. package/dist/widgets/fieldRows.js.map +1 -0
  1133. package/dist/widgets/filterCaption.js +6 -7
  1134. package/dist/widgets/filterCaption.js.map +1 -1
  1135. package/dist/widgets/filterField.d.ts +3 -7
  1136. package/dist/widgets/filterField.js +46 -35
  1137. package/dist/widgets/filterField.js.map +1 -1
  1138. package/dist/widgets/filterValueLabel.d.ts +1 -0
  1139. package/dist/widgets/filterValueLabel.js +45 -0
  1140. package/dist/widgets/filterValueLabel.js.map +1 -0
  1141. package/dist/widgets/notices.js +79 -0
  1142. package/dist/widgets/notices.js.map +1 -0
  1143. package/dist/widgets/prepareWidgetRead.d.ts +19 -2
  1144. package/dist/widgets/prepareWidgetRead.js +63 -27
  1145. package/dist/widgets/prepareWidgetRead.js.map +1 -1
  1146. package/dist/widgets/range.js +26 -21
  1147. package/dist/widgets/range.js.map +1 -1
  1148. package/dist/widgets/readForWidget.d.ts +28 -19
  1149. package/dist/widgets/readForWidget.js +33 -29
  1150. package/dist/widgets/readForWidget.js.map +1 -1
  1151. package/dist/widgets/readForWidgetBreakdown.d.ts +40 -29
  1152. package/dist/widgets/readForWidgetBreakdown.js +48 -22
  1153. package/dist/widgets/readForWidgetBreakdown.js.map +1 -1
  1154. package/dist/widgets/readForWidgetGoals.d.ts +18 -24
  1155. package/dist/widgets/readForWidgetGoals.js +52 -46
  1156. package/dist/widgets/readForWidgetGoals.js.map +1 -1
  1157. package/dist/widgets/readForWidgetRealtime.d.ts +22 -17
  1158. package/dist/widgets/readForWidgetRealtime.js +54 -27
  1159. package/dist/widgets/readForWidgetRealtime.js.map +1 -1
  1160. package/dist/widgets/readForWidgetSeries.d.ts +27 -32
  1161. package/dist/widgets/readForWidgetSeries.js +45 -82
  1162. package/dist/widgets/readForWidgetSeries.js.map +1 -1
  1163. package/dist/widgets/readMeta.d.ts +48 -0
  1164. package/dist/widgets/readMeta.js +52 -4
  1165. package/dist/widgets/readMeta.js.map +1 -1
  1166. package/dist/widgets/realtimePoll.d.ts +1 -0
  1167. package/dist/widgets/realtimePoll.js +56 -16
  1168. package/dist/widgets/realtimePoll.js.map +1 -1
  1169. package/dist/widgets/registerWidgets.js +207 -127
  1170. package/dist/widgets/registerWidgets.js.map +1 -1
  1171. package/dist/widgets/stateKeys.js +30 -0
  1172. package/dist/widgets/stateKeys.js.map +1 -0
  1173. package/dist/widgets/titleForecast.js +89 -0
  1174. package/dist/widgets/titleForecast.js.map +1 -0
  1175. package/dist/widgets/types.d.ts +4 -3
  1176. package/dist/widgets/types.js +2 -0
  1177. package/dist/widgets/types.js.map +1 -1
  1178. package/dist/widgets/viewLink.d.ts +24 -6
  1179. package/dist/widgets/viewLink.js +31 -24
  1180. package/dist/widgets/viewLink.js.map +1 -1
  1181. package/dist/widgets/widgetData.js +34 -0
  1182. package/dist/widgets/widgetData.js.map +1 -0
  1183. package/dist/widgets/widgetWindow.d.ts +1 -0
  1184. package/dist/widgets/widgetWindow.js +51 -0
  1185. package/dist/widgets/widgetWindow.js.map +1 -0
  1186. package/package.json +61 -42
  1187. package/dist/capture/getTrackerConfig.d.ts +0 -20
  1188. package/dist/capture/getTrackerConfig.js +0 -31
  1189. package/dist/capture/getTrackerConfig.js.map +0 -1
  1190. package/dist/capture/slots.d.ts +0 -8
  1191. package/dist/capture/trackerConfig.d.ts +0 -33
  1192. package/dist/charts/styles.js +0 -59
  1193. package/dist/charts/styles.js.map +0 -1
  1194. package/dist/exports/next.d.ts +0 -3
  1195. package/dist/exports/next.js +0 -3
  1196. package/dist/fields/config/SourceSelectField.d.ts +0 -14
  1197. package/dist/fields/dateRange/styles.js +0 -23
  1198. package/dist/fields/dateRange/styles.js.map +0 -1
  1199. package/dist/goals/GoalSelectField.d.ts +0 -7
  1200. package/dist/native/collections/events.js +0 -157
  1201. package/dist/native/collections/events.js.map +0 -1
  1202. package/dist/native/collections/rollups.js +0 -151
  1203. package/dist/native/collections/rollups.js.map +0 -1
  1204. package/dist/native/collections/seen.js +0 -47
  1205. package/dist/native/collections/seen.js.map +0 -1
  1206. package/dist/native/eventScan.js +0 -25
  1207. package/dist/native/eventScan.js.map +0 -1
  1208. package/dist/native/ingest/flushBatch.js +0 -60
  1209. package/dist/native/ingest/flushBatch.js.map +0 -1
  1210. package/dist/native/ingest/salt.js +0 -14
  1211. package/dist/native/ingest/salt.js.map +0 -1
  1212. package/dist/native/ingest/writeBuffer.js +0 -55
  1213. package/dist/native/ingest/writeBuffer.js.map +0 -1
  1214. package/dist/native/ingest/writeEvent.js +0 -14
  1215. package/dist/native/ingest/writeEvent.js.map +0 -1
  1216. package/dist/native/query/eventAgg.js +0 -174
  1217. package/dist/native/query/eventAgg.js.map +0 -1
  1218. package/dist/native/realtime/buildRealtime.js +0 -53
  1219. package/dist/native/realtime/buildRealtime.js.map +0 -1
  1220. package/dist/native/retention/pruneTask.js +0 -29
  1221. package/dist/native/retention/pruneTask.js.map +0 -1
  1222. package/dist/native/rollupAcc.js +0 -64
  1223. package/dist/native/rollupAcc.js.map +0 -1
  1224. package/dist/native/rollups/bucketKey.js +0 -15
  1225. package/dist/native/rollups/bucketKey.js.map +0 -1
  1226. package/dist/native/rollups/bumpRollups.js +0 -116
  1227. package/dist/native/rollups/bumpRollups.js.map +0 -1
  1228. package/dist/native/rollups/deltas.js +0 -105
  1229. package/dist/native/rollups/deltas.js.map +0 -1
  1230. package/dist/native/rollups/insertManyIfNew.js +0 -93
  1231. package/dist/native/rollups/insertManyIfNew.js.map +0 -1
  1232. package/dist/next/captureRewrites.d.ts +0 -42
  1233. package/dist/next/captureRewrites.js +0 -57
  1234. package/dist/next/captureRewrites.js.map +0 -1
  1235. package/dist/next/posthogProxyRewrites.d.ts +0 -41
  1236. package/dist/next/posthogProxyRewrites.js +0 -45
  1237. package/dist/next/posthogProxyRewrites.js.map +0 -1
  1238. package/dist/plugin/paths.js +0 -27
  1239. package/dist/plugin/paths.js.map +0 -1
  1240. package/dist/plugin/responses.js +0 -17
  1241. package/dist/plugin/responses.js.map +0 -1
  1242. package/dist/query/errors.js +0 -10
  1243. package/dist/query/errors.js.map +0 -1
  1244. package/dist/react/TrackerBoot.d.ts +0 -22
  1245. package/dist/rsc/AnalyticsScripts.d.ts +0 -30
  1246. package/dist/rsc/AnalyticsScripts.js +0 -41
  1247. package/dist/rsc/AnalyticsScripts.js.map +0 -1
  1248. package/dist/surfacing/queue.js +0 -60
  1249. package/dist/surfacing/queue.js.map +0 -1
  1250. package/dist/surfacing/retryPolicy.js +0 -15
  1251. package/dist/surfacing/retryPolicy.js.map +0 -1
  1252. package/dist/tracker/autoCapture.d.ts +0 -48
  1253. package/dist/tracker/consent.d.ts +0 -24
  1254. package/dist/tracker/consent.js +0 -48
  1255. package/dist/tracker/consent.js.map +0 -1
  1256. package/dist/tracker/loadScript.d.ts +0 -14
  1257. package/dist/tracker/pageTracking.d.ts +0 -17
  1258. package/dist/tracker/registry.d.ts +0 -27
  1259. package/dist/tracker/sinks/ga4.d.ts +0 -21
  1260. package/dist/tracker/sinks/native.d.ts +0 -22
  1261. package/dist/tracker/sinks/plausible.d.ts +0 -14
  1262. package/dist/tracker/sinks/posthog.d.ts +0 -14
  1263. package/dist/tracker/sinks/umami.d.ts +0 -13
  1264. package/dist/tracker/sinks/vendor.d.ts +0 -14
  1265. package/dist/view/sections/styles.js +0 -74
  1266. package/dist/view/sections/styles.js.map +0 -1
  1267. package/dist/widgets/WidgetViewLink.js +0 -17
  1268. package/dist/widgets/WidgetViewLink.js.map +0 -1
  1269. package/dist/widgets/cardChrome.d.ts +0 -8
  1270. package/dist/widgets/cardChrome.js +0 -46
  1271. package/dist/widgets/cardChrome.js.map +0 -1
  1272. package/dist/widgets/comparison.js +0 -57
  1273. package/dist/widgets/comparison.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,715 @@
1
1
  # @10x-media/analytics
2
2
 
3
+ ## 4.0.0-alpha.1
4
+
5
+ ### Major Changes
6
+
7
+ - Payload 4 support. `next` and `@payloadcms/next` are no longer peers: the `/next` entry is replaced by a framework-neutral `/routes` entry (`captureRoute`, `ingestRoute`, `ingestPreflight`), and the deprecated `captureRewrites` and `posthogProxyRewrites` are removed. The plugin's Local API calls pass `overrideAccess` explicitly, as Payload 4 applies access by default. Its own stuck-job guards are gone, since Payload 4's `processingUntil` lease re-runs a killed job, and `jobsConcurrency` leaves the adapter contract; jobs access follows Payload 4's admin-only defaults. The system collections (hits, aggregates, state, cache, sync) opt out of Payload 4's default versions and authorship; providers and goals opt out of versions, so no old secret lands in `_versions`. The Mongo state store asks for `returnDocument: 'after'`.
8
+
9
+ The admin UI is restyled on Payload 4's tokens, with no rem and Payload's colors as they are; contrast follows Payload's enhanced contrast mode. The view's toolbar is laid out like Payload's list controls: the window caption on the start side; Site, Data source and Date range as menu buttons, Compare and an icon Refresh on the end side; filter chips on their own row. Chart readouts are Payload's popover. Bars are as tall as a Payload control, and `BarList` now draws `fill="soft"` by default (pass `fill="solid"` for the old look); every bar sits on a track, solid bars fill with `--color-bg-brand`, and `--analytics-bar-fill-hover` is new. The goals widget names the comparison once, in its caption. The sidebar stat is set like a Payload field and the New badge is Payload's own pill. Requires Payload `4.0.0-beta.7`.
10
+
11
+ ## 1.0.0-beta.15
12
+
13
+ ### Minor Changes
14
+
15
+ - **Consent modes: a slot that waits for the consent manager can count without storing anything on the device, before an answer and after a refusal.** `capture.withoutConsent` decides what a held slot does in each phase without consent, and the plugin still stores no consent state and makes no legal decision ([Consent](https://docs.10xmedia.de/analytics/consent)).
16
+
17
+ **Behavioral:** the default is `'cookieless'`. A slot `capture.gate` holds now counts before the visitor answers and after a refusal, where 1.0.0-beta.14 sent nothing until `setGate(true)`: native as it always did, Plausible and Umami with their usual script, PostHog in posthog-js's cookieless mode. Each request still carries the visitor's IP address and user agent to the vendor or to native ingest. To keep 1.0.0-beta.14 exactly, set one option: `analytics({ capture: { withoutConsent: 'off' } })`, which renders the same tracker config and snippets and sends nothing without consent. An install that leaves the option unset while a held slot can count logs one line per boot naming the default. Whether a site may count without consent is the operator's decision: update the privacy policy and confirm with the data protection officer before shipping the default ([From 1.0.0-beta.14](https://docs.10xmedia.de/analytics/upgrading/beta-15)).
18
+
19
+ **Upgrade actions**
20
+
21
+ 1. Set `capture.withoutConsent`: `'off'` for 1.0.0-beta.14's behaviour, `'cookieless'` to keep the default, `{ pending, refused }` per phase, or a function `({ slot, adapterId, kind, phase }) => 'cookieless' | 'off'`.
22
+ 2. With a PostHog slot that counts without consent, turn on the project's **Cookieless tracking** (Settings, Web analytics), or PostHog drops those events, and give the read `apiKey` the `project:read` scope so the adapter can check it.
23
+ 3. Behind a proxy, set `trustedProxyHops` or `trustedPlatform`: cookieless counting tells visitors apart by a hash of the client address.
24
+ 4. On Postgres or SQLite in migrate mode, generate and run a migration (four nullable columns). Coming straight from 1.0.0-beta.11 on SQLite, apply the beta.12 page's providers-rebuild edit, which also removes `"without_consent"`.
25
+ 5. Update a Content Security Policy that allows the PostHog or GA4 snippet by hash.
26
+ 6. Code implementing `Tracker` or `AnalyticsApi` itself adds `mode`.
27
+
28
+ **Behavioral:** GA4 stays strict by default: its adapter declares `off` without consent, since its cookieless pings still reach Google. `ga4({ withoutConsent: 'cookieless' })` or a document's field opts it in: the snippet sets consent mode defaults, all four signals denied, before `gtag('config')`, and a grant updates `analytics_storage` alone.
29
+
30
+ **Behavioral:** a held slot that counts before an answer renders its snippet with the page, in a cookieless variant, so its first pageview counts. A grant runs it in full on the same page; a refusal or a revoke moves it to its refused level. After a revoke the only storage left is PostHog's `__ph_opt_in_out_<token>`: the PostHog sink also removes `ph_<token>_window_id`, and the GA4 sink expires `_ga` and `_ga_<id>` when the page had granted them, strict GA4 slots included.
31
+
32
+ **Behavioral:** the tracker reads no storage until some slot runs in full: the exclusion flag is read, and the old consent key deleted, only then, so a staff browser is counted by cookieless slots until that point. Plausible and Umami opt-out keys set by an exclusion or a strict refusal are cleared only once the slot runs in full.
33
+
34
+ **Behavioral:** a page restored from the back/forward cache returns held slots to their pending level, and a vendor already running in full keeps running until the manager answers again.
35
+
36
+ **Behavioral:** a PostHog read that finds cookieless pageviews reports visitors as a sum of days (`meta.visitorsAre: 'sumOfDaily'`).
37
+
38
+ **Behavioral:** the native ingest endpoint refuses an `m` other than `'f'`, `'c'` or `'a'` with `400 invalid_param` naming `m`. A beacon without `m` is stored as full.
39
+
40
+ **Breaking:** `Tracker.mode` and `AnalyticsApi.mode` are required members: each slot's `SlotMode` (`'off'`, `'cookieless'`, `'anonymous'`, `'full'`), `off` everywhere before a tracker boots.
41
+
42
+ **Additive:** `withoutConsent` on `native()`, `plausible()`, `umami()`, `posthog()` and `ga4()`, which beats the install's option for its slot; a **Without consent** field on PostHog, Plausible, Umami and GA4 provider documents (empty follows the install), with the override key `providers.collection.fields.withoutConsent`.
43
+
44
+ **Additive:** `native({ withoutConsent: 'anonymous' })` stores what native counts without consent with no visitor id, country only, and no time on page, scroll or items seen. Those hits count toward pageviews, events, goals and most breakdowns, and toward no visitor, visit or bounce rate; an erasure request naming a visitor cannot find them. Each hit stores its mode (`mode`: `f`, `c`, `a`), and server events map `identity: 'request'` to `f` and `'none'` to `a`. ([Anonymous hits](https://docs.10xmedia.de/analytics/native#anonymous-hits)).
45
+
46
+ **Behavioral:** native's time on page averages over pageviews that have a visitor, so server pageviews recorded with `identity: 'none'` no longer lower it.
47
+
48
+ **Additive:** reads gain `meta.withoutConsent` and `meta.withoutVisitor` (`{ pageviews }`) and `meta.withoutConsentDropped`. The analytics view shows the share of pageviews counted without consent; a read holding pageviews without a visitor says how many; a PostHog source whose project drops cookieless events says so in the admin. Every new note and field is translated in all built-in languages.
49
+
50
+ **Additive:** a production boot warning when a held slot can count cookielessly while neither `trustedProxyHops` nor `trustedPlatform` is set.
51
+
52
+ **Additive:** for adapter authors, `CaptureSupport.cookieless` (`{ kind: 'inherent' | 'switched', default? }`) and `withoutConsent`, `SnippetArgs` with `mode` and `withoutConsent`, `TrackerSlotConfig.withoutConsent`, `AdapterRegisterContext.countsWithoutConsent`, and the types `ConsentPhase`, `CookielessSupport`, `HeldSlotMode`, `HitMode`, `NativeWithoutConsent`, `SlotMode`, `SlotWithoutConsent`, `SnippetMode`, `WithoutConsentArgs`, `WithoutConsentFunction`, `WithoutConsentLevel` and `WithoutConsentOption`. An adapter that declares no `cookieless` sends nothing without consent, as before.
53
+
54
+ **Schema:** on SQL databases, `analytics_hits.mode`, `analytics_aggregates.pageviews_without_visitor` and `pageviews_without_consent`, and `analytics_providers.without_consent`, all nullable. Days counted before read the new counts as 0, with no recount. On a rolling deploy, a node on the old code that counts a day holding anonymous hits leaves the new counts empty until the day is counted again.
55
+
56
+ ## 1.0.0-beta.14
57
+
58
+ ### Patch Changes
59
+
60
+ - **Fix: the providers' create and edit views open again when the Provider select is narrowed.** In 1.0.0-beta.13 they answered 500 ("Functions cannot be passed directly to Client Components") on every install running the providers collection without `native()` in `adapters`, or with `providers.collection.types` naming fewer than every type: the select's `filterOptions` handed Payload's client form state option labels that were functions. It now hands over the types' values alone, which is all the client select reads. A document stored with a type the install no longer serves still opens showing its type, and its save is still refused on the **Provider** field ([Which provider types a document may have](https://docs.10xmedia.de/analytics/providers#which-provider-types-a-document-may-have)).
61
+
62
+ **Behavioral:** the docs no longer promise that `providers.collection.types` orders the select. Its first type is the default, and the select lists the types it offers in one fixed order, the order of the **Provider** column's values, so no install's column changes with the list. A host that wrapped `providers.collection.fields.provider` to map the result to values keeps working, and can drop the wrapper.
63
+
64
+ ## 1.0.0-beta.13
65
+
66
+ ### Minor Changes
67
+
68
+ - **Options for hosts that build their own admin around the plugin: a view without its nav link, a source name per reader, and a dashboard layout per reader.** None changes an install that does not set it ([A source's name](https://docs.10xmedia.de/analytics/providers#a-sources-name), [A layout per reader](https://docs.10xmedia.de/analytics/widgets#a-layout-per-reader), [Options](https://docs.10xmedia.de/analytics/analytics-view#options)).
69
+
70
+ **Additive:** `view.navLink` (default `true`). `false` registers the view at its path without its link in the admin nav, in place of filtering `admin.components.afterNavLinks`.
71
+
72
+ **Additive:** `label` on `native()`, `plausible()`, `umami()`, `ga4()` and `posthog()`: a string, a map by admin language (read in the reader's language, then `i18n.fallbackLanguage`, then `en`, as `view.navLabel` is), or `({ req, scope }) => string | Promise<string>` naming the source per reader, so staff can read "Platform (PostHog)" where a tenant reads its own site's name. Where no reader is known the name is the string, else the map's `en` or first entry, else the vendor's name; a function that throws or answers blank falls back to it with a warning. A provider document's source keeps the document's name.
73
+
74
+ **Additive:** `AnalyticsAdapter.labelFor`, the optional per-reader name a custom adapter can declare, and the types `AdapterLabelOption` and `AdapterLabelArgs`.
75
+
76
+ **Additive:** `analyticsDefaultLayout(options?)` (`@beta`) from the package root, for `admin.dashboard.defaultLayout`: the default widgets less those the reader's default source cannot serve (realtime, goals, a breakdown's dimension, a metric). It keeps widgets that are not the plugin's and widgets naming their own `dataSource`, returns the full list when the reader may read no source, and narrows `options.widgets` when given. `analyticsDefaultWidgets()` is unchanged.
77
+
78
+ - **A tenant's own PostHog captures beside the platform's PostHog.** When both capture slots resolve to PostHog, the tenant slot runs as a second posthog-js client named `tenant`, so one page captures into both projects, each with its own gate, opt-out and exclusion ([Two PostHog projects on one page](https://docs.10xmedia.de/analytics/capture#two-posthog-projects-on-one-page), [From 1.0.0-beta.12](https://docs.10xmedia.de/analytics/upgrading/beta-13#a-tenants-own-posthog)).
79
+
80
+ **Upgrade actions**
81
+
82
+ 1. To keep 1.0.0-beta.12's behavior, set `capture.slots.tenant: false`, which empties the tenant slot for every tenant.
83
+ 2. A site that loads the vendor scripts itself (`snippets={false}`) starts the tenant's project as the named client, with pageviews off: `posthog.init(token, { api_host, capture_pageview: false }, 'tenant')`. Started any other way, the tenant slot finds no client and sends nothing.
84
+ 3. A Content Security Policy that allows the PostHog snippet by hash needs the new hashes.
85
+
86
+ **Behavioral:** 1.0.0-beta.12 left the tenant slot out with a warning; it now captures, so a tenant's own PostHog project receives events it never did. The named client starts with `capture_pageview: false` and `capture_pageleave: true` and gets the tracker's own pageviews as `$pageview`; the platform's client keeps `capture_pageview: 'history_change'`. Each project counts each pageview once, and `array.js` loads once.
87
+
88
+ **Behavioral:** each PostHog slot opens, closes and is excluded on its own client: `setGate({ tenant: false })` opts out `posthog.tenant` and leaves the platform's client capturing. PostHog stores each client's state under its own project token.
89
+
90
+ **Behavioral:** PostHog's snippet no longer replaces a posthog-js already loaded on the page; it starts the slot's client on it. The snippet's text changed, so its CSP hash did.
91
+
92
+ **Behavioral:** a second slot of Plausible, Umami or GA4 is still left out of the tracker config with a warning, as before.
93
+
94
+ **Additive:** `instance` on `TrackerSlotConfig` and on `CaptureSupport.snippet`'s arguments, naming the client a slot captures with.
95
+
96
+ - **A provider document is a source only once it can read, and the Provider select offers only the types the install serves.** A document now has to be enabled, of a served type and hold the credentials its adapter reads with; `native` is offered only beside `native()`; `providers.collection.types` narrows the list; and a scoped install's documents get a **Default for this site** checkbox ([When a document is a source](https://docs.10xmedia.de/analytics/providers#when-a-document-is-a-source), [Which provider types a document may have](https://docs.10xmedia.de/analytics/providers#which-provider-types-a-document-may-have), [From 1.0.0-beta.12](https://docs.10xmedia.de/analytics/upgrading/beta-13)).
97
+
98
+ **Upgrade actions**
99
+
100
+ 1. On a scoped install running the providers collection, on Postgres or SQLite in migrate mode, generate a migration (`pnpm payload migrate:create`), review it and run it: it adds the `is_default` column to the providers table. Push mode and MongoDB need nothing ([The `is_default` column](https://docs.10xmedia.de/analytics/upgrading/beta-13#the-is_default-column)).
101
+ 2. On Postgres or SQLite, where the install runs the providers collection without `native()` in `adapters`, or sets `providers.collection.types` with another type first, the generated migration also drops the **Provider** column's `native` default. No stored value changes ([The `provider` column](https://docs.10xmedia.de/analytics/upgrading/beta-13#the-provider-column)).
102
+ 3. Enter the read credentials of any provider document that lacks them, or switch it off.
103
+
104
+ **Behavioral:** a provider document missing the credentials its adapter reads with is no longer listed as a source, fills no capture slot whatever capture fields it holds, and is no tenant's own source under a `fallback` policy. 1.0.0-beta.12 listed it and showed an empty state. A document whose credential fails to decrypt is still listed, as a failing source. `providers.resolve` installs decide for themselves.
105
+
106
+ **Behavioral:** the **Provider** select offers `native` only while `adapters` holds `native()`, and defaults to the first type it offers rather than `native`. Saving a document with a type the install does not serve is refused with a message on that field; a stored document keeps its type until it is saved.
107
+
108
+ **Additive:** `providers.collection.types` lists the types documents may have, in the order the select offers them; an unknown id, or a list leaving no served type, fails the boot. `analyticsProviderFields({ types })` takes the same list.
109
+
110
+ **Additive:** on a scoped install, the **Default for this site** checkbox (`isDefault`) in the provider document's sidebar, at most one per scope, a second refused on save. `providers.collection.defaultAccess` (a field access function or `{ create, update }`) decides who may set it, following `connectionAccess` when unset; `providers.collection.fields.isDefault` replaces the field. The flagged document's source also fills the tenant capture slot when it captures.
111
+
112
+ - **Tenants can read the platform's shared source, and each tenant picks the source its readers open on.** On a scoped install, `sources` decides per shared config adapter whether a tenant's own members read their tenant through it, and `defaultSource` with the provider document's **Default for this site** checkbox decides a tenant's default source ([Letting tenants read a shared source](https://docs.10xmedia.de/analytics/multi-tenancy#letting-tenants-read-a-shared-source), [A tenant's default source](https://docs.10xmedia.de/analytics/multi-tenancy#a-tenants-default-source), [From 1.0.0-beta.12](https://docs.10xmedia.de/analytics/upgrading/beta-13)).
113
+
114
+ **Upgrade actions**
115
+
116
+ 1. Check `access.crossScope` functions that query a database or a service: a gate may now be asked once per scope and adapter in a request, so keep it cheap or memoize it per request.
117
+ 2. Keep a `named` gate able to answer from `{ req }` alone: the providers and goals collections still ask it without `scope`.
118
+
119
+ **Behavioral:** the `access.crossScope` gates are asked with `{ req, scope, adapterId }`: `named` with the scope a reader names, `aggregate` with `'*'` or `null`, `unscopedSource` with the tenant and the config adapter's id. A gate written for `{ req }` keeps working, but where 1.0.0-beta.12 asked it once per request it may now run once per scope and adapter.
120
+
121
+ **Behavioral:** a widget or a document panel whose stored data source its reader can no longer read reads the scope's default source and says so in a note, rather than failing. The query endpoint does not substitute: a `source` it cannot read still answers `404 unknown_source`.
122
+
123
+ **Additive:** `sources: { [adapterId]: { tenants } }`, with `tenants` one of `'staff'` (the default, what 1.0.0-beta.12 did), `'tenant'` (the tenant's members always read it, narrowed to their tenant), `'fallback'` (they read it until they read a source of their own) or `({ req, scope, adapterId, ownSources }) => boolean`. Anything but `'staff'` needs an adapter with `capabilities.scopedQueries`, or the boot fails naming `sources.<id>.tenants`. A policy never widens which scope a user reads: a tenant user still gets `400 untrusted_scope` for `scope=*` or another tenant. Jobs read as `SYSTEM` and ask no policy, and capture is unaffected.
124
+
125
+ **Additive:** under `'fallback'` the view and the providers list tell a tenant's users the numbers are the platform's until they add a source, and `GET /api/_x/sources` answers `notice: 'platformFallback'`. A provider save switches the next request to the tenant's own source.
126
+
127
+ **Additive:** `defaultSource: 'tenantFirst' | 'platformFirst' | ({ req, scope, sources }) => string | undefined`. A tenant's default is its document flagged **Default for this site**, then this rule, then what 1.0.0-beta.12 picked; the sources endpoint's `defaultId`, the view, widgets without a data source, the document panel, the read helpers and the warm task follow it. `sources` and `defaultSource` fail the boot without `scope.resolve`, and `'platformFirst'` without `platformAdapter`.
128
+
129
+ **Additive:** the types `AnalyticsSourceOptions`, `SourcePolicy`, `SourcePolicyFunction`, `OwnSource`, `SourceRef`, `DefaultSourceRule` and `DefaultSourceFunction`; `CrossScopeAccess` takes the optional `scope` and `adapterId`.
130
+
131
+ ## 1.0.0-beta.12
132
+
133
+ ### Minor Changes
134
+
135
+ - **Adapters: one meaning per metric, a leaner contract, and the vendor adapters brought in line.** `avgDuration` is time on page and the new `visitDuration` time per visit on every source; capabilities say which operators each dimension takes and where each metric can be read; and an adapter reaches its vendor through the plugin's lanes and releases what it holds per Payload instance ([Adapter contract](https://docs.10xmedia.de/analytics/reference/adapter-contract), [Providers](https://docs.10xmedia.de/analytics/providers)).
136
+
137
+ **Upgrade actions**
138
+
139
+ 1. A widget saved on **Time on page** against Plausible or Umami reads **Not available for this data source**: pick **Time per visit** in its drawer, and name `visitDuration` where a stat row or an `analyticsStat` named `avgDuration` for them.
140
+ 2. With sync on Postgres or SQLite in migrate mode, the generated migration adds the sync collection's `visit_duration` column.
141
+ 3. A custom adapter: declare `capabilities.filters` as the operators each filterable dimension takes, drop `filterOperators`, `perPageQuery`, `batchPageReport` and `rateLimit.quotaModel`, serve a per-visit time as `visitDuration`, declare `kind` on each `capture.proxy.routes` entry, stamp `meta.fetchedAt` with the time it read the source (`ctx.now()`), take the Payload instance first in an `ingest.track`, release per-instance resources in `close(payload)`, and implement `registerSchema` when `register` adds collections ([Writing your own adapter](https://docs.10xmedia.de/analytics/reference/adapter-contract#writing-your-own-adapter)).
142
+ 4. Code of your own that reads `capabilities` from the sources or query endpoint reads the operators per dimension from `filters`.
143
+ 5. A self-hosted PostHog whose toolbar links should open the app: pass `posthog({ uiHost })`.
144
+
145
+ **Breaking:** `avgDuration` is engaged time per pageview on every source and `visitDuration` engaged time per visit; until now a vendor's `avgDuration` was its time per visit. GA4 answers `avgDuration` as `userEngagementDuration` over `screenPageViews` (under every breakdown but `event` and `goal`) and `visitDuration` as `averageSessionDuration`; Plausible and Umami no longer declare `avgDuration`, and their per-visit time is `visitDuration` ([Time on page and time per visit](https://docs.10xmedia.de/analytics/providers#time-on-page-and-time-per-visit)).
146
+
147
+ **Breaking:** `capabilities.metricReach` says where a metric is read when not under every dimension, and the query endpoint answers `unsupported_metric` outside it. Plausible reads `scrollDepth` only by, filtered by or for one page, and `bounceRate` and `visitDuration` under every breakdown but `goal`; Umami's pageviews, visits, bounce rate and time per visit are whole-site numbers, its visitors are not read by `goal`, and its conversions only by `goal`. The view and the pickers leave out what a source cannot answer.
148
+
149
+ **Breaking:** `capabilities.filters` is a `FilterOperatorMap`, the operators each filterable dimension takes, and `filterOperators`, `perPageQuery`, `batchPageReport` and `rateLimit.quotaModel` are gone. The `capabilities` the sources and query endpoints answer follow: `filters` maps each dimension to its operators, where it was a list of dimensions beside `filterOperators`, and `filterOperators` and `perPageQuery` are gone from them ([Sources endpoint](https://docs.10xmedia.de/analytics/reference/endpoints#sources-endpoint)). `visits` and `sessions` must answer one number. A source answers series by `minute`, `hour` or `day` only: the engine folds weeks and months from days unless the source declares `calendarBuckets: true`.
150
+
151
+ **Breaking:** what an adapter throws decides the error code: a `status`, a gRPC `code` and `retryAfterMs` are read, so throw `ProviderHttpError`. `AdapterRegisterContext` gains the required `resolveTimezoneStrict` and `revenue`, which matters only to code that builds one.
152
+
153
+ **Breaking:** `ServerTrack`, the `track` of an adapter's `ingest`, takes the Payload instance first, `(payload, event, opts?)`, where it took `(event, opts?)`.
154
+
155
+ **Breaking:** `meta.fetchedAt` is when the source was read, never the range's end as the built-in adapters stamped it: stamp it from the new `AdapterContext.now`, the plugin's clock. The engine replaces a `fetchedAt` later than the moment it got the answer, or one it cannot read, with that moment, and a cached answer keeps the stamp it was stored with ([Results](https://docs.10xmedia.de/analytics/reference/adapter-contract#results)).
156
+
157
+ **Behavioral:** GA4's Data API client runs without retries of its own, since the lane retries.
158
+
159
+ **Behavioral:** PostHog captures each single-page app navigation (`capture_pageview: 'history_change'`), so its pageview totals rise. A self-hosted `host` takes capture itself, through its capture paths alone, instead of PostHog Cloud's US region, `region` is ignored for it, and the snippet names no `ui_host` unless `uiHost` is set. With `scopeProperty` set, the snippet registers the request's scope as a super-property, so every event the SDK sends carries its tenant.
160
+
161
+ **Behavioral:** a tenant capture slot filled by the same vendor as the global slot (a tenant's own PostHog beside the platform's) is left out of the tracker config with a warning, where it used to init onto the platform's SDK and send into the platform's project.
162
+
163
+ **Behavioral:** a read naming `visits` from a source that serves only `sessions`, as native does, or the other way round, is answered from the one it serves under the name it asked for: at the query endpoint, where it answered `400 unsupported_metric`, in the widgets and in the document panel.
164
+
165
+ **Behavioral:** a vendor's average with no value reads `null`, not `0`. The sync collection gains `visitDuration`, writes a metric a source did not report as `null`, and its first run after the upgrade moves each GA4, Plausible and Umami row's stored `avgDuration` there once ([Sync](https://docs.10xmedia.de/analytics/sync#time-per-visit-moved-to-visitduration)).
166
+
167
+ **Additive:** `visitDuration`; `AnalyticsRow.samples`, the weights a row's averages carry; `metricReach` (`MetricReach`), `semantics`, `filterLookbackDays`, `calendarBuckets`, `perItemQuery` and `upstreamAware` on the capabilities; `ctx.upstream`, `ctx.remainingMs` and `ctx.payload` for sending each vendor request through its lane ([Requests to the vendor](https://docs.10xmedia.de/analytics/reference/adapter-contract#requests-to-the-vendor)); the optional `attach`, `close(payload)` and `registerSchema`, `close` running once per Payload instance an adapter was attached to and on `payload.destroy()`, and for an adapter built from a provider document once the document changes, goes away or sits unused; `AdapterContext.now`; `recommendedTtl.today`, which caps an answer reaching into the current day whatever `cache.ttl` says, for a source cheap to read again; `ga4({ currency })`, whose invalid code throws when the adapter is built, `posthog({ uiHost })` and `Ga4ClientOptions`; the types `sdks` takes, `Ga4Sdk`, `Ga4Client`, `Ga4ReportResponse` and `Ga4ReportRow` (the last three `@beta`), `MaxmindSdk` and `MaxmindReader`, typed by shape, so the real packages fit them and the package's own declarations import neither `@google-analytics/data` nor `maxmind`: an app without them type-checks with `skipLibCheck` off; provider documents of type **Payload** (`native`), with GA4 currency and PostHog scope property fields; `analyticsProviderFields()`, `adapterFromProviderDoc` and `SECRET_PATHS` (`@beta`) for keeping provider settings in a document of your own; `providers.collection.fields`.
168
+
169
+ - **Admin UI: one stylesheet, Payload's own components, accessible tables, right-to-left layouts and one meaning per label.** The view, the widgets and the Analytics tab share one stylesheet in Payload's CSS layer and Payload's own date picker, pills and loading shimmer; every list is a real table; charts mirror in right-to-left languages; and every editor-facing string reads in plain words in all 11 languages ([Customizing](https://docs.10xmedia.de/analytics/customizing), [Translations](https://docs.10xmedia.de/analytics/reference/translations)).
170
+
171
+ **Upgrade actions**
172
+
173
+ 1. Regenerate the import map (`pnpm payload generate:importmap`).
174
+ 2. Move admin CSS that targeted a removed class to its replacement (below). A rule that had to outrank an inline style no longer needs `!important`, and unlayered admin CSS now wins over the plugin's.
175
+ 3. Move translation overrides of removed keys to their replacements, since an override of a removed key now fails the boot, and keep the placeholders the changed strings take.
176
+ 4. A host collection grouped under the string `'Analytics'` beside the plugin's collections moves to their group, **Analytics settings**: build its `admin.group` from each language's `adminGroup` string in `translations` from `@10x-media/analytics/i18n`.
177
+ 5. Custom widgets, views and fields: read `BreakdownRow.dimensionValue` for the stored value, handle `null` metric values, pass `RealtimeCounter` its `label` and `timezone` and `TrendPoint` its `at`, and handle the new statuses in a `switch` over them.
178
+
179
+ **Breaking:** the admin reads one stylesheet in Payload's `payload` CSS layer instead of inline styles and injected `<style>` tags. Removed classes: `.analytics-view__table` (now `.analytics-table`), `__bars-head` and `__bars-head-dimension` (the table's own header row), `__scroll` (`.analytics-table__scroll`), `__sort`, `__sort--metric` and `__sort--secondary` (`.analytics-table__sort`), `__value` (`.analytics-table__value`) and `__date` (the range picker). A `BarList` is a `<table>` with only each row's label a button, a `TrendChart` carries a hidden data table and draws in a fixed `viewBox`, the breakdown's tab and panel ids are generated, the plugin's selects carry no `#field-analytics-*` ids, a widget card's title is an `h2`, and a missing value is a dash with a hidden "no value" beside it ([Admin styles](https://docs.10xmedia.de/analytics/upgrading/beta-12#admin-styles)).
180
+
181
+ **Breaking:** the custom range is Payload's `DatePicker`, written once both days are picked; `DateRangeField` stores UTC midnight of each picked day, and the view's and the widgets' ranges stop at today.
182
+
183
+ **Breaking:** translation keys removed: `viewFrom`, `viewTo`, `viewSortAscending`, `viewSortDescending`, `widgetRealtimeCaption` (now the counted `pluralKeys.liveVisitors` and `livePageviews`), and `goalFieldValue`, `goalFieldValueFixed`, `goalFieldValueProp` and `goalFieldValuePropHelp` (now `goalFieldAmount`, `goalFieldAmountHelp`, `goalFieldAmountProp`, `goalFieldAmountPropHelp` and `goalErrorCurrencyRequired`). `viewErrorRetryAfter` takes `{{duration}}` and `viewFilterRemove` takes `{{filter}}`. `TranslationKey` is `SingularKey | PluralVariant`. A `translations` override of a removed key fails the boot, naming it, where it used to be ignored ([Translations](https://docs.10xmedia.de/analytics/reference/translations)).
184
+
185
+ **Breaking:** labels renamed in every language: **Last 12 months** (was "Last year"), **Time on page** (was "Avg. time") and **Visits** (was "Sessions"). `visits` and `sessions` are one count: a source serving both keeps `sessions`, and `?metric=visits` is rewritten to it. A visitors total that adds up each day's visitors (`meta.visitorsAre: 'sumOfDaily'`, native over more than one day) reads **Visitors, counted per day**. `viewNavLabel`, `viewTitle` and `tabAnalytics` read in the admin's language. The goals, providers and sync collections sit in a nav group of their own, **Analytics settings** (the `adminGroup` key, a map by language), where 1.0.0-beta.11 grouped them under the string `'Analytics'`, so the nav names the view's **Analytics** link once.
186
+
187
+ **Breaking:** a metric value is `number | null`, where `null` means no data: `AnalyticsRow.metrics`, `AnalyticsResult.totals`, `BreakdownRow.value`, `SeriesPoint.value`, `WidgetSeriesResult.total` and `previousTotal`, and `TrendPoint.value` are `MetricValue`s. An average with nothing to average over reads as a dash with no delta, ranks last and breaks a trend line, where it read `0`.
188
+
189
+ **Breaking:** `BreakdownRow.label` is the display label, `''` for no value (was `'(none)'`), and the stored value is the new `dimensionValue`. `RealtimeCounter` requires `label` and `timezone` and takes an optional `caption`; `TrendPoint.at` is required. `WidgetReadStatus`, `WidgetRealtimeStatus` and `FieldReadStatus` gain `busy`, `invalid`, `no-access`, `no-scope`, `misconfigured` and `host-refused`, `WidgetReadStatus` and `FieldReadStatus` also `range-too-long`, and `readForWidgetRealtime` no longer throws. `AnalyticsViewClientProps` takes `endpoints` in place of `apiRoute` and a required `countryFlags`, and `AnalyticsViewProps` loses `pluginOptions`: the view reads the options the plugin resolved.
190
+
191
+ **Breaking:** `readForWidgetSeries` and the trend surfaces read by week past 31 days and by month past 120. The built-in widgets' default exports, and `AnalyticsStatField` and `AnalyticsPanelField` from `/rsc`, are synchronous components that suspend, where they were async functions, so code awaiting one as a function gets a Suspense element; the two fields are `@internal`, exported for the import map alone. Admin requests send `credentials: 'same-origin'` (were `'include'`).
192
+
193
+ **Behavioral:** a read that fails for a while (a timeout, a rate limit, a source down) reports `busy`, **The analytics tool is busy right now.** with a **Try again** control, as the view words it, where it read **Not available for this data source**; `unavailable` is left for a source that cannot answer the read at all. The Analytics tab keeps the headline numbers that arrived when a comparison, a series or a breakdown fails, and says the panel is incomplete with a retry. A widget whose saved custom range names a day before 1970, or no real day, reports `invalid` where it read the last 30 days.
194
+
195
+ **Behavioral:** no widget or field holds the page on a source. Every built-in widget renders its card at once behind its own Suspense boundary, a stat field past two seconds says **Still loading. Reload the page in a moment to see the numbers.**, and the Analytics tab reads nothing while the document renders: it starts from what the cache holds and reads when the tab opens.
196
+
197
+ **Behavioral:** **New** is shown only for a document with no path, or one created inside the date range; an older document with nothing counted shows zeros and **No visits in this date range.** Every surface says what a read says about its numbers: days still being counted, days that could not be counted, rare values grouped, where the data starts or ends when the range reaches past it, times in UTC because the zone could not be found, goals the source could not load (the trend widget included), and when the numbers were last updated.
198
+
199
+ **Behavioral:** dashboard cards fill their row, with the window on the title's line and the **Open in Analytics** link pinned to the bottom; a bucket still counting is drawn dashed and labelled "so far"; the overview shows at most five card columns; filter chips read as words (**Country is Germany**); value labels carry country flags. The realtime card reads its minutes in the reporting timezone, names the zone on its last time label and in every tooltip, and draws three labels, so they no longer overlap on a narrow card.
200
+
201
+ **Behavioral:** breakdowns, goals and widget lists are tables with sortable headers, charts carry a data table for screen readers, live counts are announced at most once a minute, deltas are Payload pills, and in a right-to-left language the layout, the chart axes and the arrow keys mirror. Each view step is a browser history entry written without a server round trip.
202
+
203
+ **Behavioral:** editor-facing labels, descriptions and hints in all 11 languages are rewritten for a non-technical reader: the native source is called **Payload**, a goal's slug is its **Short code**, goals are listed as **Built-in goals** and **Your goals**, and a goal's amount and currency are one control. No stored value changed. Plausible's **Website address** and **Script ID** fields each have help of their own, and a provider's write-only key field keeps its help text in every language. Languages the plugin ships no strings for read English, label maps fall back to Payload's `fallbackLanguage` first, `pt` is Brazilian Portuguese and counted phrases follow each language's plural rules.
204
+
205
+ **Additive:** `view.Component`, `countryFlags` (`false`, or `{ Component }` for flags of your own, with the flag route `GET /api/_x/flags/:code` mounted for `true`) and `widgets.overrides` ([Customizing](https://docs.10xmedia.de/analytics/customizing)); the `WidgetCard` family, `WidgetSuspense` and `WidgetShimmer` from `/rsc` and the view's building blocks from `/client`, all `@beta`; `FilterValueField`, offering a filter the dimension's top values; `analyticsTab({ breakdowns, liveVisitors, sources, report })`; the document endpoint's `fresh=1`; `TrendPoint.inProgress` and `TrendPoint.upcoming` (the rest of today, drawn as an empty axis); `FieldReadResult.incomplete` and `retryAfterMs`; `TrendChart`'s `maxTicks` (`@beta`), the most time labels it draws; the translation keys `adminGroup`, `stateRangeTooLong`, `stateFailed`, `stateClampedFrom`, `stateClampedTo`, `stateClampedBetween`, `statePartsFailed`, `providerErrorScriptId`, `providerFieldDomainHelp` and `providerFieldScriptIdHelp`; `pluralKeys`; `BuiltInWidgetSlug`; `AnalyticsComponent`; `QueryFetchError.code`; `WidgetView` and `WidgetViewProps`.
206
+
207
+ - **Consent: the site's consent manager drives a gate, and the plugin stores no decision.** Whether an install needs consent, and for which tracking, is the site's call, so the plugin has no default and no stored state: `capture.gate` says which capture slots wait, and the consent manager opens or closes them with `setGate` on every page load ([Consent](https://docs.10xmedia.de/analytics/consent), with a c15t recipe and a generic one).
208
+
209
+ **Upgrade actions**
210
+
211
+ 1. Set `capture.gate`: `'all'` holds every slot until the manager answers, `'off'` captures without waiting, a list names the slots that wait, and a function `({ slot, adapterId, kind }) => boolean` decides per slot. `({ kind }) => kind !== 'native'` reproduces what 1.0.0-beta.11 did by default.
212
+ 2. Replace `tracker.consent('granted')` and `consent('denied')` from `useAnalytics()` with `setGate(true)` and `setGate(false)` (`setGate({ tenant: true })` for one slot), called from your consent manager's bridge on every page load, and again on a `pageshow` event whose `persisted` is true.
213
+ 3. Remove `persistConsent`, and the imports of `CONSENT_STORAGE_KEY`, `CONSENT_QUEUE_LIMIT`, `ConsentState`, `createConsentQueue`, `readConsent` and `writeConsent` from `/tracker`, and of `CaptureConsentOption`, `ConsentMode` and `ConsentResolver` from the package root (`CaptureGate` types the new option).
214
+ 4. Import `AnalyticsScripts` and `getTrackerConfig` from `@10x-media/analytics/site`, and replace `TrackerBoot` with `<AnalyticsScripts />` or `<AnalyticsProvider>`.
215
+ 5. A consent manager that injects the vendor scripts itself: pass `snippets={false}` and let it load each slot's `snippet.scripts`.
216
+ 6. A Content Security Policy that allows the vendor snippets by hash needs the new hashes: the snippets changed with the gate and the exclusion prelude.
217
+ 7. Where `capture.gate` holds native, server code that knows the visitor's answer passes `identity: 'request'` to `trackServerEvent`, `purchase`, `refund` or `trackGoalAction` ([What the gate does not cover](https://docs.10xmedia.de/analytics/consent#what-the-gate-does-not-cover)).
218
+
219
+ **Breaking:** `capture.gate` is required whenever a capture slot can fill, the native one included, and the boot stops without it, naming the choices.
220
+
221
+ **Breaking:** no consent decision is stored. The tracker never reads the `analytics:consent` key 1.0.0-beta.11 wrote, and deletes it once a slot opens, so a returning visitor is pending until the manager answers again.
222
+
223
+ **Breaking:** `Tracker.consent` and `useAnalytics().consent` are replaced by `setGate(state)` and the read-only `gate`: both are required members of `Tracker`, `setGate` of `AnalyticsCommands` and `gate` of `AnalyticsApi`. Code that implements `Tracker` itself, such as a test double, adds them. `TrackerOptions.persistConsent` is removed.
224
+
225
+ **Breaking:** `TrackerSlotConfig.requiresConsent` is `gated`, now required. A tracker config a browser cached from 1.0.0-beta.11 is still read, and a slot carrying neither field is held.
226
+
227
+ **Behavioral:** while a slot is pending its events wait in a queue of 100 (engagement only for a native slot); a decision before the tracker exists is applied when it boots. Closing a slot drops its queue, stops delivery and, where the vendor's script may have run, sets its own opt-out (Plausible's and Umami's keys, PostHog's `opt_out_capturing()`, GA4's disable flag and a consent mode update denying all four storage types). Opening one clears that opt-out unless the browser is excluded, injects the slot's snippet and sends what waited. A slot the config does not fill reads `closed` and ignores answers.
228
+
229
+ **Behavioral:** nothing reads or writes the browser's storage before a slot opens: the exclusion flag is read, and the old consent key deleted, when the first slot opens, so `excluded` reads `false` until then. Before any answer only these touch it: the signed exclusion link a staff member opens and the `=0` link (which removes the flag when set), the GA4 snippet of a slot that does not wait (it reads the exclusion flag), and the vendors' opt-out switches a refusal sets under `snippets: false`.
230
+
231
+ **Behavioral:** a page restored from the back/forward cache puts its held slots back to pending rather than keeping the answer it had, which the visitor may have revoked in another tab since; the manager answers again from its `pageshow` handler.
232
+
233
+ **Behavioral:** server tracking (`trackServerEvent`, the server `purchase` and `refund`, and `trackGoalAction`) records an event as no visitor's by default while `capture.gate` holds a slot native may fill: no visitor id, and no location, device or language read from the request. With `gate: 'off'` it keeps the request's visitor, and `identity: 'request'` or `'none'` decides per call. An `ip` or `userAgent` passed without an `identity` and set aside by that default is logged once.
234
+
235
+ **Behavioral:** on the server, a slot that does not wait renders its vendor snippet with the page and a slot that waits renders nothing until it opens; its snippet travels as data in the tracker config. A server that knows the decision passes `gate`, as in `<AnalyticsScripts config={tracker} gate={{ tenant: true }} />` ([Server render](https://docs.10xmedia.de/analytics/consent#server-render)).
236
+
237
+ **Behavioral:** PostHog's snippet initialises with `opt_out_persistence_by_default`, so its opt-out also deletes its own storage, and lifting the opt-out sends no `$opt_in`.
238
+
239
+ **Additive:** `setGate`, `gate`, `GateState`, `GateStatus`, `CaptureGate` and `CaptureGateArgs`; `gate` and `snippets` on `<AnalyticsScripts />`, `<AnalyticsProvider>` and `createTracker`; the beacon's `ageMs`, the time an event waited in the browser (at most a day), which ingest subtracts so a held event is filed when it happened rather than when its slot opened. `loadScript` stays on `<AnalyticsProvider>` and `createTracker` for a framework's script loader.
240
+
241
+ - **Entry points: a `/site` entry, a smaller `/tracker`, one stylesheet and release tags on every export.** Each entry now exports what its environment uses and nothing it should not load: a site's server components import `/site`, a page's browser code `/tracker`, `/attributes` and `/react`, and the admin `/rsc` and `/client` ([Entry points](https://docs.10xmedia.de/analytics/reference/entry-points)).
242
+
243
+ **Upgrade actions**
244
+
245
+ 1. Move the imports the table below names.
246
+ 2. Regenerate the import map (`pnpm payload generate:importmap`).
247
+ 3. Where your bundler does not follow CSS imports, or a `BarList` or `TrendChart` renders outside the admin, import `@10x-media/analytics/styles.css`.
248
+
249
+ **Breaking:** exports removed since 1.0.0-beta.11, and what replaces them:
250
+
251
+ | Entry | Removed | Use instead |
252
+ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
253
+ | `/rsc` | `AnalyticsScripts`, `AnalyticsScriptsProps`, `getTrackerConfig` | the same from `/site` |
254
+ | `/rsc` | `TrackerConfig`, `TrackerSlotConfig` | the same types from `/site`, `/tracker` or `/types` |
255
+ | `/rsc` | `widgetCardStyle`, `widgetLabelStyle` | `WidgetCard`, or the `analytics-card analytics-widget` classes |
256
+ | `/react` | `TrackerBoot`, `TrackerBootProps` | `<AnalyticsScripts />` or `<AnalyticsProvider>` |
257
+ | `/tracker` | `GOAL_ATTRIBUTE`, `OUTBOUND_EVENT`, `DOWNLOAD_EVENT`, `SCROLL_EVENT` | the same from `/attributes` |
258
+ | `/tracker` | `readExclusion`, `writeExclusion`, `subscribeExclusion`, `readExclusionParam` | `tracker.excluded` and `tracker.exclude()`, or `excluded` and `setExcluded` from `useAnalytics()` |
259
+ | `/tracker` | `CONSENT_QUEUE_LIMIT`, `CONSENT_STORAGE_KEY`, `ConsentState`, `createConsentQueue`, `readConsent`, `writeConsent` | `setGate`, `GateState` and `GateStatus` |
260
+ | `/tracker` | `createNoopTracker`, `createAutoCapture`, `AutoCapture`, `AutoCaptureHandlers`, `createPageTracking`, `PageTracking`, `createScriptLoader`, `acquireTracker`, `TrackerLease`, `PAGEVIEW_BUFFER_MS` | `initTracker`, `createTracker` and the components |
261
+ | `/tracker` | `createNativeSink`, `createGa4Sink`, `Ga4SinkArgs`, `GA4_DISABLE_PREFIX`, `createPlausibleSink`, `PLAUSIBLE_IGNORE_KEY`, `createPosthogSink`, `createUmamiSink`, `UMAMI_DISABLED_KEY`, `VendorSinkArgs`, `Sink`, `TrackerEvent` | nothing: the tracker builds its own sinks |
262
+ | root | `CaptureConsentOption`, `ConsentMode`, `ConsentResolver` | `CaptureGate` |
263
+ | root | `PlatformReadAccess`, `ScopesResolver` | `CrossScopeAccess`, `ScopeListResolver` |
264
+
265
+ **Breaking:** the package declares `"sideEffects": ["*.css"]`, where it declared `false`: every admin module imports the plugin's one stylesheet, which the package also exports as `@10x-media/analytics/styles.css`.
266
+
267
+ **Breaking:** the widget drawer's pickers and the `goalField()` picker are registered at new server component paths (`@10x-media/analytics/rsc#SourceSelectFieldServer` and its siblings), which read the scope on the server. The five paths 1.0.0-beta.11 registered stay exported, marked `@deprecated` with the server path that replaces each, so an import map generated before the upgrade still renders them, keyed by the scope the page's cookies select; the widget filter's value field and the goal amount control are new paths and render nothing until the import map is regenerated ([Component paths](https://docs.10xmedia.de/analytics/reference/stability#component-paths)).
268
+
269
+ **Behavioral:** the package depends on `undici` and `ipaddr.js` for the guarded provider fetch, and on `country-flag-icons` for the flag route.
270
+
271
+ **Behavioral:** every export carries a release tag. An untagged export is stable; `@beta` (the dashboard widgets and the `widgets` option, the `WidgetCard` family, `BarList`, `TrendChart`, `RealtimeCounter`, the widget drawer's pickers, the view's building blocks with `view.Component`, the flag seams, the toolkit for building adapters in `providers.resolve`, `SYSTEM`, `ReadPrincipal` and `GatedScope`, the wire shapes `WireGoal`, `GoalsResponse`, `RawEventInput` and `HitType`, and the GA4 structural types) may change in a minor release; `@internal` is exported for Payload's import map alone; `@deprecated` still works and names its replacement. The component paths the plugin registers are frozen for the 1.x line ([Stability](https://docs.10xmedia.de/analytics/reference/stability)). Of the exports 1.0.0-beta.11 shipped untagged, these are now `@internal`: `AnalyticsView`, `AnalyticsViewProps`, `AnalyticsStatField` and `AnalyticsPanelField` from `/rsc`, and `AnalyticsNavLink`, `AnalyticsNavLinkProps` and `DateRangeField` from `/client`. These are now `@beta`: the built-in widget components, `analyticsDefaultWidgets`, `widgetFilters`, `CustomWidgetDef` and `WidgetFilter`; `BarList`, `TrendChart`, `TrendPoint` and `RealtimeCounter`; `AnalyticsViewClient`, `AnalyticsViewClientProps` and `ViewGoal`; the widget drawer's pickers and their props, `useAnalyticsSources`, `useFilterCapabilities`, `useAnalyticsGoals`, `AnalyticsSources`, `FilterCapabilities`, `WireGoal` and `GoalsResponse`.
272
+
273
+ **Additive:** the `/site`, `/attributes`, `/migrations` and `/migrations/drop-legacy-mongo` entries and `./styles.css`; the adapter contract types from every adapter entry, `/next` and `/testing`; the view's `@beta` building blocks from `/client` ([Customizing](https://docs.10xmedia.de/analytics/customizing)); `settleAnalytics(payload)` from `/testing`, which waits for the plugin's background work (cache writes, the native engine's upkeep, a write buffer it flushes) before a test reads back or destroys Payload ([Testing](https://docs.10xmedia.de/analytics/reference/adapter-contract#waiting-for-background-work)). Each entry's public surface is recorded in an API report that CI compares on every change, so nothing public changes without a reviewed diff.
274
+
275
+ - **Content items, engagement and what the tracker counts.** An offer, a banner or a product card can have analytics of its own; time on page and scroll depth are measured for the whole visit rather than its first seconds; and the tracker leaves out what is not a visit ([Content items](https://docs.10xmedia.de/analytics/items), [Time on page and scroll depth](https://docs.10xmedia.de/analytics/native#time-on-page-and-scroll-depth)).
276
+
277
+ **Upgrade actions**
278
+
279
+ 1. Code with an exhaustive `Record` or `switch` over `MetricKey` or `DimensionKey` adds `impressions`, `interactions` and `visitDuration`, and `currency` and `item`. Both unions may grow again in a minor release.
280
+ 2. Code that implements `Tracker` itself accepts the third argument of `track` (and adds `purchase`, `refund`, `setGate` and `gate`, which the revenue and consent entries describe).
281
+ 3. An end-to-end suite that asserts on captured hits from an automated browser sets `capture.skip: { automation: false }`.
282
+ 4. To use items: bind a collection with `collections: { offers: { item: true } }`, mark the element that renders a document with `itemAttributesFor(payload, { collection, id, name })` or a ref from `signItemRef`, and regenerate the import map.
283
+
284
+ **Breaking:** `MetricKey` gains `impressions`, `interactions` and `visitDuration`, and `DIMENSION_KEYS` gains `currency` and `item`. `ResolvedAutoCapture` gains a required `items`, `AnalyticsBinding` an optional `item`, and `Tracker['track']` an optional third argument, `{ item }`.
285
+
286
+ **Behavioral:** the tracker sends a pageview the moment a page is tracked instead of holding it for up to ten seconds, so time on page and scroll depth are no longer capped at that moment. What the visitor does afterwards follows as an `engagement` message when the tab is hidden, the page is left or a single-page app moves on: the visible time (at most 30 minutes per message) and the extra scroll since the previous one. It is never counted as a pageview, event, visit or visitor, never reaches a vendor slot, and is filed on its pageview's day. Ingest drops a `durationMs` or `scrollDepth` sent on an event or a goal. **Active right now** reacts faster, since a visit counts from its first moment.
287
+
288
+ **Behavioral:** a page the browser only prerenders sends nothing and loads no vendor script until it is shown, then one pageview for wherever it is.
289
+
290
+ **Behavioral:** a form carrying `data-analytics-goal` or `data-analytics-event` counts its submit alone, once per submission: a click inside it no longer completes the goal, and an element tagged around a form no longer counts again on the form's submit ([Tag the element](https://docs.10xmedia.de/analytics/goals#1-tag-the-element)).
291
+
292
+ **Behavioral:** browsers reporting `navigator.webdriver`, Next draft mode pages and Payload's live preview are not counted; `capture.skip: { automation: false, previews: false }` counts them ([Pages that are not counted](https://docs.10xmedia.de/analytics/capture#pages-that-are-not-counted)).
293
+
294
+ **Behavioral:** `initTracker()` resolves the window's one tracker, shared with `AnalyticsScripts`, `AnalyticsProvider` and `useAnalytics`, and its `destroy` gives its hold back. A destroyed tracker stays quiet even when another library wrapped the history API over it.
295
+
296
+ **Additive:** content items. `collections.<slug>.item` binds a collection's documents as items; the tracker counts an item seen once at least half of it stays on screen for a second in a tab in front, sends `item_click` for the first click inside one per pageview, and credits a goal or event fired inside it. Refs a page sends carry the server's signature unless `native({ items: { signature: 'optional' } })`. `track(name, props, { item })`, `trackGoal(slug, { item })`, `purchase({ item })` and `item` on the server calls file an event under an item. `capture.autoCapture.items` turns any part off. The Analytics tab of an item reads **Views**, **Viewers**, **Clicks**, **Click rate**, **Conversions** and the pages it was seen on (`report: 'auto' | 'item' | 'page'` on `analyticsTab` and the stat fields), leaving out a list the source cannot rank, the analytics view gains a **Content** tab, and the query endpoint takes `item=<ref>` on a source declaring `capabilities.perItemQuery`. Vendors receive `item_click` (GA4 as `select_promotion`) and an item's id and name on goals and events.
297
+
298
+ **Additive:** the dependency-free `@10x-media/analytics/attributes` entry: `goalAttributes()`, `eventAttributes()`, `itemAttributes()`, `itemRef()`, the attribute names and the event names, for marking up a link, a Lexical converter or a shared component without loading Payload. Auto-capture reads `data-analytics-event` and `data-analytics-prop-*` beside the goal attributes, and `analyticsLinkFields()` adds a goal picker to any link field ([Integrations](https://docs.10xmedia.de/analytics/integrations)).
299
+
300
+ - **Jobs, the read cache and reaching the sources.** The plugin's background work runs as Payload jobs under leases, reads are cached in a collection of their own, and every vendor source is reached through its own lane with retries and a circuit breaker, so one slow or failing source no longer holds up the others ([Caching](https://docs.10xmedia.de/analytics/cache), [Maintenance](https://docs.10xmedia.de/analytics/native#maintenance)).
301
+
302
+ **Upgrade actions**
303
+
304
+ 1. Run Payload's job runner for the plugin's tasks, and let your scheduler call `/api/payload-jobs/run` through `jobs.access.run` ([Who may run jobs](https://docs.10xmedia.de/analytics/native#who-may-run-jobs)). `jobs: false` registers no task.
305
+ 2. Move `sync.cron` to `jobs.tasks.sync.cron` and `cache.warm.cron` to `jobs.tasks.warm.cron`.
306
+ 3. Where `payload_jobs` exists (1.0.0-beta.11 registered sync, warming or native retention), delete the queued runs of `analytics-prune-events` and `analytics-warm-cache` in the upgrade's migration, on Postgres before the task enum changes, with the statement the [upgrade page](https://docs.10xmedia.de/analytics/upgrading/beta-12#edits-before-you-run-it) gives; on MongoDB the predefined `drop-legacy-mongo` migration does it, so an install that ran warming without `native()` runs that migration too.
307
+ 4. If a second auth collection queues or cancels your own jobs with `overrideAccess: false`, set `jobs.access` to allow it.
308
+ 5. Remove the old cached reads from Payload's key-value store with `deleteLegacyCache({ payload })` from `@10x-media/analytics/migrations`; on MongoDB `dropLegacyNative` already does.
309
+ 6. An install that keeps provider settings in a store of its own (`providers.resolve`) calls `refreshProviders()` when they change.
310
+ 7. Code with an exhaustive `switch` over `AnalyticsErrorCode` or `QueryErrorCode` adds `rate_limited` and `source_misconfigured`.
311
+
312
+ **Breaking:** once the plugin registers a task, every job control your Payload config left unset admits only users of the admin collection: `jobs.access.run` (the `/run` and `/handle-schedules` endpoints), `jobs.access.queue`, `jobs.access.cancel`, the `payload-jobs` collection (composed over your `jobsCollectionOverrides`) and the `payload-jobs-stats` global. A control you set is never changed, and the boot says once which ones it restricted.
313
+
314
+ **Breaking:** the warm task is `analytics-warm`, no longer `analytics-warm-cache`, and it and `analytics-sync` follow `jobs.queue` and their own `jobs.tasks` entries. Warming replays the reads readers made recently, per scope, rather than the dashboard's default layout, and `cache.warm` takes `{ windowHours, maxReads }`. `jobs: false` refuses sync and warming at boot.
315
+
316
+ **Breaking:** reads are cached in the `analytics-cache` collection, or a `cache.store` of your own, instead of Payload's key-value store, and expired entries are deleted; live counts are kept in each instance's memory only. Cache keys changed, so every read reaches its source once after the upgrade.
317
+
318
+ **Breaking:** each vendor source has its own lane: 16 requests in flight across an instance's vendor sources and 4 per source by default (`cache.concurrency`), with retries, `Retry-After` capped at ten minutes and a circuit breaker. `rateLimit.maxConcurrent` is the size of a source's lane. A scope with too many reads waiting on their sources answers `429 rate_limited` with `Retry-After: 2` ([Reaching the sources](https://docs.10xmedia.de/analytics/cache#reaching-the-sources)).
319
+
320
+ **Breaking:** read errors carry what to do about them. A read the vendor refuses as asked (HTTP 400, 413, 414, 422, 431, gRPC invalid argument) answers `400 invalid_param` with `param: 'query'`, where it answered `503`; a refused key or property (HTTP 401, 403, 404), a credential that will not decrypt, or a provider host the install does not allow answers the new `502 source_misconfigured` with `param: 'source'` or `'host'`; the live endpoint answers `400` and `502` in the same cases. A native read the database refuses as written answers `400 invalid_param` too, a missing table, column or privilege `502 source_misconfigured`, and a statement timeout counts as a timeout. `AnalyticsErrorCode` gains `rate_limited` and `source_misconfigured` ([The codes](https://docs.10xmedia.de/analytics/reference/endpoints#the-codes)).
321
+
322
+ **Behavioral:** an expired entry is answered at once while it refreshes in the background (`meta.stale`), `meta.sourceError` says when the refresh failed because of how the source is set up, and `cache.timeoutMs` bounds only reads with nothing cached. `order` and `limit` are applied by the engine before an answer is cached, whatever the source sent, and a breakdown with a `limit` and no `order` is ranked by its first metric, highest first.
323
+
324
+ **Behavioral:** native reads have a lane of their own, outside `cache.concurrency`: 8 reads at once, or on Postgres a third of the host pool's `pool.max`, between 1 and 8. On a source every tenant shares (native, or a config adapter read per tenant), one tenant holds at most half of the lane, and the circuit breaker counts failures per tenant, so one tenant's failing reads do not stop the others'. A read SQLite refuses before it runs answers `503` and does not count toward the breaker.
325
+
326
+ **Behavioral:** each task runs at most four minutes per run and leaves the rest to the next one, under one lease per task in `analytics-state`, so two workers never do the same work. A killed run's lease lets the next run in within two minutes for sync and warming. On Cloudflare D1, where the plugin runs no SQL of its own, sync and warming hold their leases through Payload's database API one two-minute slot at a time, so a killed run frees its lease within four. An install with sync or warming but no `native()` gains the `analytics-state` collection for them, renamed through `jobs.state`.
327
+
328
+ **Behavioral:** sync reads as the system rather than a user, writes a metric the source did not report as `null`, and is not passed through `hooks.afterRead`, since it stores the source's own numbers.
329
+
330
+ **Behavioral:** the sources, goals, tracker config and ingest endpoints answer an unexpected failure with `500 internal` in the error envelope, where Payload answered with its own error, and log it (ingest at most once a minute); an `access.read` that throws is such a failure, and the refresh endpoint answers one with `500 internal` too, where it answered `503`. The capture proxy answers a bare `500` ([Which endpoint answers which](https://docs.10xmedia.de/analytics/reference/endpoints#which-endpoint-answers-which)).
331
+
332
+ **Behavioral:** on a local SQLite file, the read cache's writes and its sweep of expired entries queue behind the native engine's writes and are skipped while the host holds a transaction open in the same process, rather than waiting on the process's own lock until they fail; a skipped write only means the next read asks the source again ([Transactions on SQLite](https://docs.10xmedia.de/analytics/native#transactions-on-sqlite)).
333
+
334
+ **Behavioral:** what time it is comes from Payload's clock (`getCurrentDate`) for every day cut, lease and cache stamp on the server, so a test that sets that clock moves them together, and every duration, timeout, budget and rate limit runs on a monotonic clock that a jump of the wall clock does not stretch or cut. The boot's warnings (the job controls it restricted, spoofable addresses, packages loaded by name, a SQLite adapter's `transactionOptions`) wait for the server that serves requests: none prints while `next build` collects page data.
335
+
336
+ **Additive:** the `jobs` option (`queue`, and `queue` and `cron` per task, `false` to register none); `cache.store` (`CacheStore`), `cache.collection` and `cache.concurrency`; `hooks.afterRead` for observing or reshaping each read ([Observing reads](https://docs.10xmedia.de/analytics/cache#observing-reads)); `refreshProviders`; `ProviderHttpError` and `parseRetryAfter`; `TASK_NAMES`, `AnalyticsTaskName`, `ScheduledTask`, `AdapterJobs`; `CACHE_SLUG`, `STATE_SLUG` and `SYNC_SLUG`; `sync.collection.overrides`.
337
+
338
+ - **Native engine: raw hits counted into daily totals, with real visits, on MongoDB, Postgres and SQLite.** The engine stores one row per hit, counts each closed day into exact daily totals per scope, hostname and value, and answers a read from the totals of closed days and the raw hits of today, of hours and of filtered reads. Visits are counted from the hits, so bounce rate and time per visit are real ([Native engine](https://docs.10xmedia.de/analytics/native)).
339
+
340
+ **Upgrade actions**
341
+
342
+ 1. Export `analytics-events` and `analytics-rollups` first if you want to keep their numbers: the old storage is not converted.
343
+ 2. On a development database Payload pushes its schema to, before the first boot: on Postgres run `DELETE FROM payload_jobs WHERE task_slug::text IN ('analytics-prune-events', 'analytics-warm-cache');` when `payload_jobs` exists, then `DROP TABLE analytics_events, analytics_rollups, analytics_seen CASCADE;` and `DROP TYPE enum_analytics_events_type;`, and the push does the rest; start a pushed SQLite file again from a new one ([Push mode](https://docs.10xmedia.de/analytics/upgrading/beta-12#push-mode)).
344
+ 3. Run the migration for your database ([Storage and the database](https://docs.10xmedia.de/analytics/upgrading/beta-12#storage-and-the-database)):
345
+ - **MongoDB:** `pnpm payload migrate:create analytics_storage --file @10x-media/analytics/migrations/drop-legacy-mongo`, then `pnpm payload migrate`. It drops the old collections and deletes the old salts, the old cached reads and the queued runs of the retired tasks.
346
+ - **Postgres in migrate mode:** generate it with `pnpm payload migrate:create analytics_storage`, answering **create table** and **create enum** at every prompt, then edit it:
347
+ - add `IF EXISTS` to the three `DROP CONSTRAINT` statements on `payload_locked_documents_rels`;
348
+ - when `payload_jobs` exists, which it does once 1.0.0-beta.11 registered any task (sync, warming or native retention), make `DELETE FROM "payload_jobs" WHERE "task_slug"::text IN ('analytics-prune-events', 'analytics-warm-cache');` the first statement of its `db.execute` block: it deletes the queued runs of the two retired task names, and the cast keeps it valid on a task enum that lacks either label;
349
+ - with the providers collection, move its `ALTER TYPE ... ADD VALUE 'native'` out of `db.execute` and run it on the adapter's own connection, outside the migration's transaction.
350
+ - **SQLite in migrate mode:** generate it the same way, then move the three `DROP TABLE` statements below the rebuild of `payload_locked_documents_rels`, with the providers collection remove `"ga4_currency"` and `"posthog_scope_property"` from both column lists of `INSERT INTO __new_analytics_providers`, and when `payload_jobs` existed before the upgrade end `up` with `DELETE FROM payload_jobs WHERE task_slug IN ('analytics-prune-events', 'analytics-warm-cache');`.
351
+ - On Postgres and SQLite, end `up` with `deleteLegacySalts({ payload })`, and optionally `deleteLegacyCache({ payload })`, from `@10x-media/analytics/migrations`; on a scoped install with the providers collection, each tenant's `native` provider document follows them in the same `up`.
352
+ 4. Replace `native({ retentionDays, rollupRetentionDays })` with `native({ retention: { rawDays, aggregateDays } })`, and pass the Payload instance to `NativeAdapter.flush(payload)`.
353
+ 5. Run a jobs runner for `analytics-maintain`, or set `jobs: false` to leave the upkeep to reads and ingest.
354
+ 6. On SQLite, open the database with `sqliteAdapter({ wal: true, busyTimeout: 5000 })` so the engine runs on worker threads, and leave `transactionOptions` unset. Run native on a database file: it refuses an in-memory database and an embedded replica.
355
+ 7. On Postgres, size the host pool (`postgresAdapter({ pool: { max } })`) with the engine's share in mind: its long reads and counts take at most a third of it ([Production note (Postgres)](https://docs.10xmedia.de/analytics/native#production-note-postgres)).
356
+
357
+ **Breaking:** `analytics-events`, `analytics-rollups` and `analytics-seen` are replaced by `analytics-hits` (one row per hit), `analytics-aggregates` (daily totals) and `analytics-state` (salts, day markers, leases and heartbeats). The new collections are hidden, have no REST or GraphQL endpoints, and take text ids the engine makes. The daily salts move from Payload's key-value store to `analytics-state` and each is deleted once the third UTC day after its own begins.
358
+
359
+ **Breaking:** native needs MongoDB 5.0, Postgres 12 or SQLite 3.35 or later, and refuses Cloudflare D1 at boot; keep a D1 install on vendor adapters. On SQLite it opens a connection of its own to the database file, so an in-memory database, an embedded replica or a second copy of libsql stops it (`502 source_misconfigured`, warned once). MongoDB-compatible services (Amazon DocumentDB, Azure Cosmos DB, Firestore) are not supported, and below MongoDB 5.0 reads and counts refuse while hits are still stored.
360
+
361
+ **Breaking:** raw hits are kept 90 days by default and daily totals for every day. Filtered and hourly reads, which read raw hits, reach back as far as `retention.rawDays`; a sale's and a refund's rows outlive it as tombstones without their visitor, until their day's totals go ([Retention](https://docs.10xmedia.de/analytics/native#retention)).
362
+
363
+ **Breaking:** `native()` registers the `analytics-maintain` task (every 15 minutes), which turns Payload's jobs on for an install that had none; `analytics-prune-events` is gone ([Maintenance](https://docs.10xmedia.de/analytics/native#maintenance)).
364
+
365
+ **Breaking:** `NativeAdapter.flush(payload)` takes the Payload instance it writes for, since every engine structure is kept per instance.
366
+
367
+ **Breaking:** server events never join the host's transaction: a rolled-back order keeps its hit, and on SQLite one tracked inside an open transaction is written once it ends. A server event without `req`, `ip` or `userAgent` belongs to no visitor, and `event.timezone` only picks the day of its salt ([Server events and host transactions](https://docs.10xmedia.de/analytics/native#server-events-and-host-transactions)).
368
+
369
+ **Behavioral:** a visit is a visitor's hits on one hostname with no gap over 30 minutes, attributed to the pageview that opened it; hour series are the reporting timezone's local hours; breakdowns list no `(other)` row; a referrer is stored only on the pageview that opened a visit, engagement rows carry no visitor attributes, and a click id is stored by name, never its value.
370
+
371
+ **Behavioral:** native reads say what their numbers are: `meta.partial` (days not counted yet), `meta.capped` (values folded away, whose raw hits are gone), `meta.failed` (days whose counting was given up), `meta.clamped` with `dataFrom` and `dataTo` (an end of the range past the raw hits kept), `meta.asOf` (today's snapshot), `meta.visitorsAre` and `meta.timezoneUnresolved`. Native never sets `meta.sampled`.
372
+
373
+ **Behavioral:** daily totals keep at most 10,000 pages and 100 currencies per hostname a day, with the other caps of `native({ caps })`; what a day sends beyond a cap stays exact while its raw hits are kept and is folded into one row after that ([Daily totals and caps](https://docs.10xmedia.de/analytics/native#daily-totals-and-caps)).
374
+
375
+ **Behavioral:** maintenance counts days that are waiting first, oldest first, then works through the scopes in turn from a saved cursor, skipping a scope with no new hits since its last pass. A day whose count fails three times is marked failed: reads use an earlier count of it when there is one, and `rebuildDays` counts it again ([Maintenance](https://docs.10xmedia.de/analytics/native#maintenance)).
376
+
377
+ **Behavioral:** today is read live from its raw hits up to 5,000 hits on Postgres and 2,000 elsewhere, and above that from a snapshot taken in the background, served for one to five minutes by how busy the day is (`meta.asOf`). A read spends at most three seconds on closed days it finds uncounted and never starts one it cannot finish; a day left out is counted in `meta.partial.missingDays` and the read is cached for the realtime TTL. A read whose window reaches into today is cached 10 seconds at most, whatever `cache.ttl` says, and read again rather than served stale once it expires ([TTLs](https://docs.10xmedia.de/analytics/cache#ttls)).
378
+
379
+ **Behavioral:** on Postgres the engine shares the host's pool: its long reads, counts and analytical transactions hold at most a third of `pool.max` connections, all its work at most one fewer than the pool, so the host always keeps one; a count a read starts carries a `statement_timeout` (on MongoDB a shared `maxTimeMS`). Each call the engine makes to a host resolver gets a fresh local request.
380
+
381
+ **Behavioral:** a live read fails as a whole, `503` with `Retry-After`, when any part of it fails. A write buffer batch that fails as a whole (a lock, a lost connection) is retried once after 500 ms and then dropped; only a batch a row of which was refused is retried row by row.
382
+
383
+ **Behavioral:** on a local SQLite file the engine runs its statements on three worker threads of its own when the database is in WAL mode with a busy timeout of at least 5,000 ms, so counting a busy day no longer freezes the process; otherwise it stays on the main thread under stall budgets and the boot warns once. `native({ sqlite: { thread } })` or `ANALYTICS_SQLITE_THREAD` sets it ([SQLite](https://docs.10xmedia.de/analytics/native#sqlite)).
384
+
385
+ **Behavioral:** the boot warns when a local SQLite file's adapter sets `transactionOptions`. `@libsql/client` 0.14 opens every connection after a transaction without the adapter's busy timeout, so from the second transaction on a write fails at once with `SQLITE_BUSY` while another connection holds the lock (the engine's, a jobs worker's, another instance's), and libsql may then lose later writes on that connection. Leave `transactionOptions` unset, as Payload does by default ([Transactions on SQLite](https://docs.10xmedia.de/analytics/native#transactions-on-sqlite)).
386
+
387
+ **Behavioral:** the public ingest path reads nothing from the database per beacon. Buffered and deferred hits are written on `SIGINT` as on `SIGTERM`, and `process.exit()` logs how many were lost.
388
+
389
+ **Behavioral:** a `geoResolver` that throws, or answers something other than text for a field, has the event stored without a location instead of failing the beacon, and is logged at most once an hour.
390
+
391
+ **Additive:** `native({ retention, caps, collections, items, sqlite, today })` and `buffer.maxPending`; `meta.failed` and `meta.dataTo` on a read's result; native filters with `matches` on Postgres and MongoDB, for patterns that JavaScript, Postgres and MongoDB read alike (no nested quantified groups), any other answering `400 invalid_param` with `param: 'filters'`; `rebuildDays`, `NativeAdapter.rebuild` and the maintain task's `rebuild` input count a stretch of days again ([Rebuilding days](https://docs.10xmedia.de/analytics/native#rebuilding-days)); `dropLegacyNative`, `deleteLegacySalts` and `deleteLegacyCache` from `@10x-media/analytics/migrations`; `HITS_SLUG`, `AGGREGATES_SLUG`, `MAINTAIN_TASK_SLUG` and `SESSION_DIMENSIONS` from `/adapters/native`; `ingestRoute` and `ingestPreflight` from `/next`, for taking beacons in a route of your own.
392
+
393
+ - **Options: renamed options fail the boot, and the boot checks what it used to accept.** Every option is now checked when the plugin builds the Payload config, and a value of the wrong shape, a key no option takes at any level, an id that names no adapter, or a combination the plugin cannot honor stops the boot with a message naming the path ([Options](https://docs.10xmedia.de/analytics/reference/options)).
394
+
395
+ **Upgrade actions**
396
+
397
+ 1. Load the config once (the dev server, or any `payload` command) and rename every option the error names, each listed with its replacement. The `native()` options fail first, in a message of their own, so it can take two runs. On an install without `scope.resolve`, remove `access.platformRead` and `scopes` instead: their replacements only apply to a scoped install, and there every cross-scope gate is `isAdminUser`.
398
+ 2. Set `capture.gate` ([consent](https://docs.10xmedia.de/analytics/consent#which-slots-wait)) and, on a scoped install, `scope.member` ([multi-tenancy](https://docs.10xmedia.de/analytics/multi-tenancy)).
399
+ 3. Set `revenue: true` or `revenue: { currency }` if the install reports revenue.
400
+ 4. In `widgets.register`, replace `requires: { perPageQuery: true }` with `requires: { path: true }`, and `filterOperators` with `filters` naming each operator with its dimension.
401
+ 5. Fix whatever else the boot refuses: the message names the option. With several invalid options, the one named first may differ from earlier releases.
402
+
403
+ **Breaking:** these 1.0.0-beta.11 options are removed, not deprecated, and fail the boot with an error naming the replacement and linking [Removed options](https://docs.10xmedia.de/analytics/upgrading#removed-options):
404
+
405
+ | Removed | Use instead |
406
+ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
407
+ | `scopeResolver` | `scope.resolve` |
408
+ | `scopes` | `scope.list` for the scopes the cron jobs run over, `scope.label` for the view caption, on a scoped install; remove it from an unscoped one |
409
+ | `access.platformRead` | `access.crossScope` (a function grants all three cross-scope gates) on a scoped install; remove it from an unscoped one |
410
+ | `capture.consent` | `capture.gate`: `'all'`, `'off'`, a list of slots, or `({ slot, adapterId, kind }) => boolean`; `({ kind }) => kind !== 'native'` reproduces the old default |
411
+ | `sync.collectionSlug` | `sync.collection.slug` |
412
+ | `sync.hidden` | `sync.collection.hidden` |
413
+ | `sync.cron` | `jobs.tasks.sync.cron` |
414
+ | `cache.warm.cron` | `jobs.tasks.warm.cron`; `cache.warm` keeps `windowHours` and `maxReads` |
415
+ | `goals.collection.enabled` | `goals.collection: false` |
416
+ | `native({ retentionDays })` | `native({ retention: { rawDays } })` |
417
+ | `native({ rollupRetentionDays })` | `native({ retention: { aggregateDays } })` |
418
+
419
+ **Breaking:** `adapters` is required in the option type. It may be empty only with `disabled: true`.
420
+
421
+ **Breaking:** a string `reportingTimezone` that is not a time zone fails the boot, where it used to read as UTC. A resolver answering one logs a warning once per value.
422
+
423
+ **Breaking:** options that only mean something on a scoped install fail the boot without `scope.resolve`: `scope.list`, `scope.label`, `scope.member`, `access.crossScope`, an adapter id in `capture.slots.tenant`, `capture.paths.tenant`, a `collections.<slug>.scopeField` other than `false`, and an explicit `goals.collection.scopeField` or `providers.collection.scopeField`.
424
+
425
+ **Breaking:** `disabled: true` checks every option and keeps the plugin's database schema, rather than returning the config untouched. A switched-off install therefore gains the plugin's collections: generate its migration as for a running one ([Switching it off](https://docs.10xmedia.de/analytics/reference/options#switching-it-off)).
426
+
427
+ **Breaking:** what 1.0.0-beta.11 let through now fails the boot: a key no option takes, at any level of the options (a misspelled `cache.tll` included); two adapters with the same `id`; a `cache.ttl` value that is not a whole number of seconds, 0 or more (`'300'` included); a `cache.timeoutMs`, `sync.lookbackDays`, `capture.proxy.timeoutMs` or `capture.proxy.maxBodyBytes` value that is not a whole number of at least 1; a `widgets.disabled` slug that names no widget of the install, and a `widgets.register` entry without its `slug`, `component` and `label`; `goals.collection` set to `null`, `0` or `''` (it takes `true`, `false` or an object); a `translations` key that is not one of the plugin's own, a key this release removed among them ([Translations](https://docs.10xmedia.de/analytics/reference/translations)).
428
+
429
+ **Breaking:** a `widgets.register` entry's `requires` takes only `metrics`, `dimensions`, `filters`, `realtime`, `perItemQuery` and `path`. The two 1.0.0-beta.11 keys that are gone fail the boot, naming their replacement, rather than being ignored and offering the widget where it was left out: `perPageQuery` is `path: true`, and `filterOperators` is `filters` naming each operator with its dimension, such as `filters: [{ dimension: 'page', operator: 'contains' }]` ([Custom widgets](https://docs.10xmedia.de/analytics/widgets#custom-widgets)).
430
+
431
+ **Breaking:** a collection override is checked against what the plugin reads and writes. An override may not rename a plugin collection (its `slug` option does), remove, rename or retype a field the plugin writes, drop an index it declares, add a required field without a fixed `defaultValue`, or turn off `timestamps` on the providers and goals collections; `overrides` must be a function, and on Postgres a table or index name over 63 characters fails. The checks run again at init against the config every plugin has assembled ([Renaming the plugin's collections](https://docs.10xmedia.de/analytics/reference/options#renaming-the-plugins-collections)).
432
+
433
+ **Breaking:** a goal path pattern holds at most 32 segments and four `**`; `**` inside a segment no longer crosses slashes (write `/docs/**` for any depth), and a path deeper than 128 segments matches nothing ([Path globs](https://docs.10xmedia.de/analytics/goals#path-globs)).
434
+
435
+ **Behavioral:** GA4's Data API client and `maxmind` are handed over through `sdks`, so a traced or standalone build ships them: `sdks: { ga4: { BetaAnalyticsDataClient }, maxmind: { open } }`. Without it the plugin still loads them by name, and a production boot warns.
436
+
437
+ **Additive:** options new since 1.0.0-beta.11, each covered by the entry for its theme: `routes.base`, `trustedPlatform`, `sdks`, `hooks.afterRead`, `jobs`, `revenue`, `scope`, `access.crossScope`, `capture.gate`, `capture.exclusion`, `capture.allowedOrigins`, `capture.skip`, `capture.autoCapture.items`, `collections.<slug>.scopeField` and `item`, `goals.purchase`, `goals.collection.fields`, `providers.collection.fields`, `connectionAccess` and `sourceAccess`, `providers.hosts`, `view.Component`, `widgets.overrides`, `countryFlags`, `cache.store`, `cache.collection`, `cache.concurrency`, `sync.collection.overrides`, and on `native()`: `retention`, `caps`, `collections`, `items`, `sqlite`, `today` and `buffer.maxPending`.
438
+
439
+ - **Revenue: money is opt-in, sales and refunds have calls of their own, and an order counts once.** `purchase` and `refund` are the revenue calls, in the browser and on the server; a sale the browser and a payment webhook both record counts once, in the visit that made it; and only server code can subtract money ([Revenue](https://docs.10xmedia.de/analytics/revenue)).
440
+
441
+ **Upgrade actions**
442
+
443
+ 1. If the install reports revenue, set `revenue: true`, or `revenue: { currency: 'EUR' }` to report in one currency per install or per scope.
444
+ 2. If an amount the browser sends should win over a goal's fixed value, as before, set `revenue: { browserAmounts: 'trust' }`.
445
+ 3. Give a currency to every goal that has an amount: a goal saved earlier with an amount and no currency asks for one on its next save. Where the form-builder goal action's fields are out of the plugin's reach, pass `trackGoalAction({ defaultCurrency })`.
446
+ 4. Fix an invalid Plausible `revenueCurrency`, which now throws when the adapter is built.
447
+ 5. Code that implements `Tracker` itself, such as a test double, adds `purchase` and `refund`.
448
+ 6. To record sales and refunds, call `purchase()` with each order's real id and the server's `refund()` with a `refundId` of its own.
449
+
450
+ **Breaking:** money is off unless `revenue` is set. Without it the `revenue` metric is gone from every source, the `currency` dimension is not declared and every amount field is hidden (in collections, globals and blocks alike); stored amounts are kept, and turning money on shows them again. The boot warns when a config goal carries a `value` while money is off ([What disappears when money is off](https://docs.10xmedia.de/analytics/revenue#what-disappears-when-money-is-off)).
451
+
452
+ **Breaking:** `revenue.browserAmounts` defaults to `'fixed'`: a goal's fixed value wins over an amount the browser sends, which counts only for a goal without one. `'none'` ignores browser amounts and `value.prop` alike, `'trust'` keeps the old order. Server code is always believed ([Amounts from the browser](https://docs.10xmedia.de/analytics/revenue#amounts-from-the-browser)).
453
+
454
+ **Breaking:** ingest refuses a body carrying `revenue` or a negative `value` with a `400`, where 1.0.0-beta.11 ignored the one and dropped the negative amount, keeping the event: only server code subtracts money.
455
+
456
+ **Breaking:** a goal with an amount needs a currency, in the goals collection and in the form-builder goal action, through the API as much as in the admin; `trackGoalAction({ defaultCurrency })` fills it in where the action's fields are out of the plugin's reach.
457
+
458
+ **Breaking:** an invalid Plausible `revenueCurrency` throws when the adapter is built, and a blank one no longer turns Plausible's revenue on.
459
+
460
+ **Breaking:** `Tracker` and `AnalyticsCommands` gain the required `purchase` and `refund`, so code that implements either itself adds them.
461
+
462
+ **Behavioral:** each goal an event completes carries its own amount, converted from that goal's own currency. Every amount is capped at 10^12.
463
+
464
+ **Behavioral:** a built-in `purchase` goal exists without being declared, so a sale reaches `conversions` and `revenue` before anyone declares a goal. It is latent: left out of the goal picker and the tracker config, shown in the goals table only once it has conversions, returned by the goals endpoint only for `?include=builtin`, and named in the query endpoint's `builtinGoalSlugs`. `goals.purchase: false` removes it ([The built-in purchase goal](https://docs.10xmedia.de/analytics/goals#the-built-in-purchase-goal)).
465
+
466
+ **Behavioral:** without a reporting currency, a native read whose revenue adds several currencies lists them in `meta.mixedCurrencies`, and every surface says so; the `currency` dimension, on by default without `revenue.convert`, shows gross per currency.
467
+
468
+ **Additive:** `purchase({ orderId, value, currency?, items?, props? })` and `refund(...)` as server functions taking `payload`, and `purchase` on the tracker and on `useAnalytics()`; the tracker's `refund` only warns in development, since a refund is recorded server-side, from the payment webhook. `items` are the lines of a sale, forwarded to GA4 as `items` and to PostHog as a property. Server calls filed without a `path` go under `/orders`.
469
+
470
+ **Additive:** order ids. An id holds up to 255 characters and no control character: the server calls throw `AnalyticsTrackError` for one that is not, and ingest drops a beacon carrying one, still answering `202`. Native stores only a digest of it, keyed by the Payload secret, never the id itself. A sale recorded by both the browser and the webhook counts on the browser's record, in its visit, with the webhook's amount, and the webhook's record counts no event, so a visit's source, campaign and country carry the sale and `events` counts it once. The two pair only within 24 hours, unless `revenue.orderSignature: 'required'` is set and the page sends an id from `signOrderId`; a record arriving after its day was counted has that day counted again ([Recorded in the browser and by the webhook](https://docs.10xmedia.de/analytics/revenue#recorded-in-the-browser-and-by-the-webhook)). A refund counts its amount in revenue and no conversion, is keyed by its `refundId` so two partial refunds both count and a retried one counts once, and is filed with its sale's attribution ([Refunds](https://docs.10xmedia.de/analytics/revenue#refunds)).
471
+
472
+ **Additive:** `revenue.currency`, `convert`, `dimension`, `browserAmounts` and `orderSignature`, with a vendor's own revenue currency (GA4's property currency, Plausible's `revenueCurrency`) winning over `revenue.currency` for that vendor, and a `revenue.convert` answer that is unbounded or flips the sign counting as no answer; `signOrderId`; a goal's `browser: false`, which ignores completions sent from a browser; `identity` on server calls, `'none'` recording an event as no visitor's; the goal amount control with a currency picker; `analyticsLinkFields({ value: true })` for a per-link amount.
473
+
474
+ - **Security: one endpoint base, admin-only defaults, and public endpoints that trust nothing a request merely claims.** Reads default to the admin collection's users, capture never sees the admin's identity, provider documents connect only where the install allows, and the links and refs a page can send are signed ([Endpoints](https://docs.10xmedia.de/analytics/reference/endpoints)).
475
+
476
+ **Upgrade actions**
477
+
478
+ 1. Update code, CDN rules or Next routes of your own that call the old `/api/analytics/*` paths (table below), and build the paths with `analyticsRoutes(config)`. A page that boots with `initTracker({ endpoint })` passes the new config path.
479
+ 2. Give a second auth collection that should read analytics an `access.read` of your own, and widen the goals, sync or providers collection's `access` where users outside the admin collection manage them.
480
+ 3. Resolve a visit's scope from its host at the `capture` call site, never from the admin's tenant cookie ([The call site](https://docs.10xmedia.de/analytics/multi-tenancy#the-call-site)).
481
+ 4. On Vercel or behind Cloudflare, set `trustedPlatform: 'vercel'` or `'cloudflare'` in place of `trustedProxyHops`, which it excludes, or visitor countries stop being read ([Which headers to trust](https://docs.10xmedia.de/analytics/geo#which-headers-to-trust)).
482
+ 5. List your other sites whose pages post beacons in `capture.allowedOrigins`.
483
+ 6. List the self-hosted vendor hosts of your provider documents in `providers.hosts.allow`, and set `providers.hosts.allowPrivateNetwork: true` for a host on `http://` ([Where a document may connect](https://docs.10xmedia.de/analytics/providers#where-a-document-may-connect)).
484
+ 7. Turn the exclusion link on with `capture.exclusion: true`, and list your websites' addresses in `capture.exclusion.sites` so the analytics view links staff straight to each ([Excluding your own visits](https://docs.10xmedia.de/analytics/capture#excluding-your-own-visits)).
485
+ 8. Where `next.config` calls `captureRewrites` or `posthogProxyRewrites`, relay the vendor through `captureRoute` in a route handler instead, or leave `capture.paths` unset to use the plugin's own proxy ([First-party proxy](https://docs.10xmedia.de/analytics/proxy)).
486
+
487
+ **Breaking:** every endpoint moved under one base, `routes.base`, default `/_x`, with no alias at the old paths:
488
+
489
+ | 1.0.0-beta.11 | Now |
490
+ | ------------------------------------------------------------- | ------------------------------------------------------ |
491
+ | `GET /api/analytics/query`, `/sources`, `/goals`, `/document` | `GET /api/_x/query`, `/sources`, `/goals`, `/document` |
492
+ | `POST /api/analytics/refresh` | `POST /api/_x/refresh` |
493
+ | `GET /api/analytics/realtime` | `GET /api/_x/live` |
494
+ | `POST /api/analytics/ingest` | `POST /api/_x/e` |
495
+ | `GET /api/analytics/tracker` | `GET /api/_x/config` |
496
+ | `/api/analytics/p/:slot/*` | `/api/_x/p/:slot/:path*` |
497
+
498
+ `native({ ingestPath })` and `capture.paths` default to the new paths, and the tracker and the admin build them themselves. The boot refuses a base whose first segment a collection slug, a plain-object name or an earlier root endpoint would take ([Where the endpoints answer](https://docs.10xmedia.de/analytics/reference/endpoints#where-the-endpoints-answer)).
499
+
500
+ **Breaking:** `access.read` defaults to the users of the admin collection (`admin.user`), where any signed-in user read before, and the read helpers of `/rsc` are gated by it too; so does every cross-scope gate on an install without `scope.resolve`. The goals, sync and providers collections admit only the admin collection's users by default, and reading the sync collection also takes `access.read`.
501
+
502
+ **Breaking:** a `POST` another site's page makes a visitor's browser send (`Sec-Fetch-Site`) is dropped by ingest, still answering `202`, and refused by the capture proxy with `403`, unless its origin is in `capture.allowedOrigins` ([Beacons from other sites](https://docs.10xmedia.de/analytics/capture#beacons-from-other-sites)). On a scoped install the same holds for a page on a sibling subdomain whose host `scope.resolve` maps to another tenant than the request's.
503
+
504
+ **Breaking:** `captureRewrites` and `posthogProxyRewrites` from `@10x-media/analytics/next` throw when called, and are `@deprecated`: a Next rewrite to a vendor forwards every request header, the visitor's cookies and the site's `payload-token` among them, and passes the vendor's `set-cookie` back to the site. Relay the vendor through `captureRoute` instead ([First-party proxy](https://docs.10xmedia.de/analytics/proxy)).
505
+
506
+ **Breaking:** a provider document's `host` must be an `https` address. An adapter built from a document connects only to public addresses and follows no redirect on its own, and a self-hosted host the install does not list fails as `502 source_misconfigured` and captures nothing. `providers.hosts.allowPrivateNetwork: true` admits private addresses, and `http://` hosts in `providers.hosts.allow` and in the document's `host` field, which are refused without it ([Private networks](https://docs.10xmedia.de/analytics/providers#private-networks)).
507
+
508
+ **Breaking:** on a scoped install a provider document's connection (its type, host and the ids its adapter reads) changes only with `access.crossScope.named`, and any change of where a document connects clears its stored key, so enter the key again in the same save ([Changing where a document connects](https://docs.10xmedia.de/analytics/providers#changing-where-a-document-connects)). A stored credential is decrypted on a request of its own, outside the reader's transaction, and taking a beacon never decrypts one; a document whose credential does not decrypt lists as a failing source.
509
+
510
+ **Breaking:** the exclusion link is off by default and signed: `?analytics_exclude=1` no longer excludes a browser, and the tracker's `exclusionParam` option and `readExclusionParam` are gone. With `capture.exclusion: true` the parameter carries an HMAC of the scope keyed by the Payload secret, the tracker config carries only its hash, and `capture.exclusion.param` renames it. A browser already excluded stays excluded.
511
+
512
+ **Behavioral:** `?analytics_exclude=0` still counts a browser again, with no token, as soon as the page loads. It reads the flag and removes it only when the browser was excluded, where 1.0.0-beta.11 wrote `0` to storage.
513
+
514
+ **Breaking:** on Vercel and Cloudflare the visitor's country, region and city come from the platform's headers only with `trustedPlatform` set; without it no platform header is read. `trustedPlatform` and `trustedProxyHops` exclude each other.
515
+
516
+ **Breaking:** the capture proxy decides each answer's content type from its route's `kind`, sends `X-Content-Type-Options: nosniff` and sandboxes data answers; a custom adapter declares `kind` on every proxy route.
517
+
518
+ **Behavioral:** the tracker sends native only the referrer's origin and, of the page's query string, only the campaign keys (the `utm_*` keys and the names of the click ids), and `props.url` on `outbound_link` and `file_download` drops the query string, the fragment and any credentials.
519
+
520
+ **Behavioral:** the capture proxy answers `404` for a path segment holding an encoded `/` or `\`, which an upstream would read as a separator, and `405` with an `Allow` header for a `POST` to a script route. A Plausible `scriptId` that is not up to 64 letters, digits, `_` and `-` renders no snippet, and the providers collection refuses it.
521
+
522
+ **Behavioral:** the document endpoint refuses a range over 366 days with `400 range_too_long`, as the query endpoint does, and both refuse a date before 1970 with `400 invalid_param`. The analytics view names goals and the scope only to a reader `access.read` admits, even where `access.view` is wider.
523
+
524
+ **Behavioral:** nothing a vendor snippet embeds can end its `<script>` element: every value every adapter writes into an inline script goes through one escaper, `</script>` and the JavaScript line separators included.
525
+
526
+ **Additive:** the analytics view's **Your own visits** panel ([Your own visits](https://docs.10xmedia.de/analytics/analytics-view#your-own-visits)). By default it shows `?analytics_exclude=<token>` to copy and add to a site's address. With `capture.exclusion.sites`, a list of website addresses or a function per scope that may be async, it shows one row per site: **Stop counting this browser** and **Count this browser again** open the website in a new tab, and **Copy link for another browser** copies the signed link. On a multi-tenant install the platform's **All sites** view lists every tenant's sites, each with that tenant's token, for a reader `access.crossScope.named` admits. `GET /api/_x/exclusion` serves the panel and answers `sites: Array<{ address, token }>` (`ExclusionResponse`, `ExclusionSite`).
527
+
528
+ **Additive:** `captureRoute` and `CaptureRouteOptions` from `@10x-media/analytics/next`, a route handler that relays one adapter's vendor by the capture proxy's rules: no cookie or credential upstream, and no `set-cookie` back; `routes.base`, `analyticsRoutes`, `routePaths` and `DEFAULT_ROUTE_BASE`; `isAdminUser`; `trustedPlatform`; `capture.allowedOrigins`; `capture.exclusion` with `param` and `sites`; `providers.hosts`; `createGuardedFetch`, `resolveHostPolicy` and `CONNECTION_PATHS`, all `@beta`; `providers.collection.connectionAccess` and `sourceAccess`; item refs and order ids signed by the server (`signItemRef`, `itemAttributesFor`, `signOrderId`).
529
+
530
+ - **Multi-tenancy: one scope authority, membership checked on every read, and three cross-scope gates.** The host decides which tenant a request is for, through `scope.resolve`, and every surface reads that answer: the view, the widgets, the display fields, the endpoints and the read helpers. A reader must belong to the tenant they read, and reading past it takes an explicit gate ([Multi-tenancy](https://docs.10xmedia.de/analytics/multi-tenancy)).
531
+
532
+ **Upgrade actions**
533
+
534
+ 1. Rename `scopeResolver` to `scope.resolve`, `scopes` to `scope.list` (and `scope.label` for the view caption), and `access.platformRead` to `access.crossScope`. An install without `scope.resolve` removes `scopes` and `access.platformRead` instead.
535
+ 2. Add `scope.member`: `tenantMembership()` reads `@payloadcms/plugin-multi-tenant`'s tenants array, and `() => true` suits a resolver that already derives the scope from `req.user`.
536
+ 3. Make `scope.resolve` answer a visit from its host when `callSite` is `'capture'`, never from the admin's tenant cookie, and never answer `'*'`: a beacon it resolves to no tenant is answered `202` and dropped.
537
+ 4. Give every bound collection on a scoped install a `tenant` field, name another one in `collections.<slug>.scopeField`, or set `scopeField: false` to read the request's own scope.
538
+ 5. With the providers collection, create an enabled provider document of type **Payload** (`provider: 'native'`) for every tenant that should keep native analytics, at the end of the upgrade migration's `up`, through its `req` and as a user `access.crossScope.named` admits ([Scoped installs](https://docs.10xmedia.de/analytics/upgrading/beta-12#scoped-installs)); and grant `access.crossScope.unscopedSource` to the readers who should still read a shared config adapter under a tenant.
539
+ 6. Remove options that only mean something on a scoped install from an unscoped one.
540
+
541
+ **Breaking:** `scope.member` is required with `scope.resolve`. Every read refuses a tenant its user does not belong to, the read helpers of `/rsc` included, and a refused endpoint answers `400 untrusted_scope`.
542
+
543
+ **Breaking:** `scope.resolve` receives `{ req, callSite }`. At `capture` (beacons, the tracker config, the capture proxy, server tracking with a request) it is asked without the signed-in user, their cookies or their authorization header, and the timezone and currency resolvers get that same request there ([The call site](https://docs.10xmedia.de/analytics/multi-tenancy#the-call-site)). An answer of `'*'` is refused and logged: the wildcard is a reader's request, never a request's own scope. On a scoped install a request that resolves no tenant reads nothing unless the reader passes `access.crossScope.aggregate`.
544
+
545
+ **Breaking:** an install without `scope.resolve` has no scope to name: a read or a refresh naming one other than `*` answers `400 untrusted_scope`, where any signed-in user could name one. On every install a scope name over 256 characters is refused the same way.
546
+
547
+ **Breaking:** on a scoped install running the providers collection, native is granted per tenant by a `native` provider document. A tenant without an enabled one does not see the native source anywhere, gets no native beacon in its tracker config, and has its beacons dropped at ingest (still answering `202`); what it already stored is kept ([Native is a provider type](https://docs.10xmedia.de/analytics/multi-tenancy#native-is-a-provider-type)).
548
+
549
+ **Breaking:** with the providers collection, a tenant reads the sources its own provider documents grant it, filtered to the documents the reader may read (`providers.collection.sourceAccess`, by default the collection's own read access), and a config adapter only for a reader `access.crossScope.unscopedSource` admits; before, every config adapter that could narrow to a scope was readable by any tenant. On every scoped install, a config adapter that cannot narrow to a tenant is no longer among its sources at all, and naming it under a tenant answers `404 unknown_source` where it answered `403 forbidden` ([Which sources a request sees](https://docs.10xmedia.de/analytics/multi-tenancy#which-sources-a-request-sees)).
550
+
551
+ **Breaking:** a binding on a scoped install reads the document's own scope from `collections.<slug>.scopeField`, by default `'tenant'`, and the boot fails when the collection has no such field. The Analytics tab, the stat fields, the live counter and the document, sources and live endpoints all report the page's tenant rather than the reader's, and reading a document of another tenant takes `access.crossScope.named`; a reader it denies sees **Analytics for this page are not available to you** ([Whose numbers a document shows](https://docs.10xmedia.de/analytics/display-fields#whose-numbers-a-document-shows)).
552
+
553
+ **Behavioral:** `access.crossScope`, which replaces `access.platformRead` ([Removed options](https://docs.10xmedia.de/analytics/upgrading#removed-options)), is three gates: `named` (read a tenant you are not), `aggregate` (read every tenant at once) and `unscopedSource` (read a tenant through a config adapter rather than its own provider documents). A function grants all three, and the object form denies the gates it leaves out. On a scoped install every gate denies by default, as `platformRead` did; on an unscoped one each is `isAdminUser` and the option cannot be set ([Who sees what](https://docs.10xmedia.de/analytics/multi-tenancy#4-who-sees-what)).
554
+
555
+ **Behavioral:** naming your own resolved scope is no longer a cross-scope read, so it needs no gate; another tenant and `*` stay behind theirs.
556
+
557
+ **Behavioral:** a tenant capture slot left to its default takes the tenant's default source when that source captures, and otherwise the first of its sources that does, where it took the default source, and left the slot empty when that source could not capture.
558
+
559
+ **Behavioral:** the analytics view says whose numbers it shows: a reader who may aggregate gets a **Site** select offering their own site and **All sites** (`scope=*:<tenant>`), every other reader a caption naming the scope (`scope.label`), and a reader with no tenant selected is asked to choose one. A view address carrying any other `scope` is rewritten to the scope that answered.
560
+
561
+ **Behavioral:** `scope.resolve` at the `admin` call site, `reportingTimezone`, `revenue.currency` and the three cross-scope gates are each asked at most once per request, however many widgets and fields read on it.
562
+
563
+ **Additive:** `scope.label`, `tenantMembership()`; `ScopeCallSite`, `ScopeListResolver`, `ScopeLabelResolver`, `ScopeMemberAccess` and `CrossScopeAccess`; the panel's data-source switcher (`analyticsTab({ sources })`); the goals collection registered with `@payloadcms/plugin-multi-tenant` through `goals.collection.scopeField` ([Goals per tenant](https://docs.10xmedia.de/analytics/multi-tenancy#goals-per-tenant)).
564
+
565
+ - **Upgrading from 1.0.0-beta.11.** This release rebuilds the native engine's storage, leaves consent to the site's consent manager, moves every endpoint under one base and tightens who may read what, so every install has edits to make, and every Postgres or SQLite install in migrate mode has one reviewed migration to run. The other entries of this release group the changes by theme; [From 1.0.0-beta.11](https://docs.10xmedia.de/analytics/upgrading/beta-12) is the whole procedure on one page, with every change and what to do about it.
566
+
567
+ **Upgrade actions**
568
+
569
+ 1. Before the first boot, prepare a development database Payload pushes its schema to: on Postgres run the SQL under [Push mode](https://docs.10xmedia.de/analytics/upgrading/beta-12#push-mode), and start a pushed SQLite file again from a new one.
570
+ 2. Upgrade `@10x-media/analytics` together with Payload `^3.83.0` (`payload`, `@payloadcms/next`, `@payloadcms/ui`) and `@10x-media/fields`, which is now a required peer ([Supported versions](https://docs.10xmedia.de/analytics/reference/stability#supported-versions)).
571
+ 3. Load the config (the dev server, or any `payload` command) and fix what it refuses. A removed option fails it with an error naming its replacement, the `native()` options first and the plugin's own in a second message: rename each ([Removed options](https://docs.10xmedia.de/analytics/upgrading#removed-options)), but remove `access.platformRead` and `scopes` from an install without `scope.resolve`. The same checks refuse what 1.0.0-beta.11 let through, a translation override of a removed key among them, and a widget's `requires.perPageQuery` or `requires.filterOperators`, each named with its replacement.
572
+ 4. Set `capture.gate`; `({ kind }) => kind !== 'native'` keeps what 1.0.0-beta.11 did by default. Where the gate holds native, server code that knows the visitor's answer passes `identity: 'request'` to keep server events on their visitor.
573
+ 5. On a scoped install, add `scope.member`, and make `scope.resolve` answer the `capture` call site from the request's host.
574
+ 6. If the install reports revenue, set `revenue: true` or `revenue: { currency }`, and give every goal that has an amount a currency.
575
+ 7. Import `AnalyticsScripts` and `getTrackerConfig` from `@10x-media/analytics/site`, replace `consent()` calls with `setGate()`, and relay a vendor through a `captureRoute` route handler where `next.config` called `captureRewrites` or `posthogProxyRewrites`, which now throw.
576
+ 8. Regenerate the import map (`pnpm payload generate:importmap`).
577
+ 9. Migrate the database ([Storage and the database](https://docs.10xmedia.de/analytics/upgrading/beta-12#storage-and-the-database)):
578
+ - **MongoDB:** `pnpm payload migrate:create analytics_storage --file @10x-media/analytics/migrations/drop-legacy-mongo`, then `pnpm payload migrate`, where the install ran `native()` or warming: without `native()` it drops nothing and still deletes the queued `analytics-warm-cache` runs.
579
+ - **Postgres and SQLite in migrate mode:** `pnpm payload migrate:create analytics_storage`, answering **create table** (and **create enum** on Postgres) to every prompt, make the edits the upgrade page lists for your database, review the file, then `pnpm payload migrate`. Every such install needs it: the read cache is a new collection unless `cache.store` names a store of your own.
580
+ - **A scoped install with the providers collection:** end that migration's `up` with an enabled `native` provider document for every tenant that keeps native analytics ([Scoped installs](https://docs.10xmedia.de/analytics/upgrading/beta-12#scoped-installs)).
581
+ 10. Run Payload's job runner for `analytics-maintain`, and let your scheduler call it through `jobs.access.run`.
582
+ 11. On Vercel or behind Cloudflare, set `trustedPlatform` in place of `trustedProxyHops`, which it excludes, to keep visitor countries.
583
+ 12. List the origins of other sites whose pages post beacons in `capture.allowedOrigins`.
584
+ 13. Turn on `capture.exclusion`, list your websites in `capture.exclusion.sites`, and have staff leave their browsers out from the analytics view's **Your own visits** panel.
585
+ 14. List the self-hosted vendor hosts of your provider documents in `providers.hosts.allow`, and set `providers.hosts.allowPrivateNetwork: true` for one on `http://`.
586
+ 15. On SQLite, open the database with `sqliteAdapter({ wal: true, busyTimeout: 5000 })` and leave `transactionOptions` unset; native runs on a database file, not an in-memory database or an embedded replica.
587
+
588
+ **Breaking:** the native engine's old storage is not converted. Its collections are dropped by the migration, and the native reports count from the first hit stored after the upgrade; export `analytics-events` and `analytics-rollups` first to keep their numbers ([Storage and the database](https://docs.10xmedia.de/analytics/upgrading/beta-12#storage-and-the-database)).
589
+
590
+ **Breaking:** `@10x-media/fields` is a required peer, where it was optional, whether the plugin runs or is switched off, and `react-datepicker` is no longer a peer: the custom range uses Payload's own date picker.
591
+
592
+ **Behavioral:** `@payloadcms/db-postgres` is no longer an optional peer: nothing in the package imports it.
593
+
594
+ ## 1.0.0-beta.11
595
+
596
+ ### Patch Changes
597
+
598
+ - Updated dependencies:
599
+ - @10x-media/fields@0.1.0-beta.8
600
+
601
+ ## 1.0.0-beta.10
602
+
603
+ ### Minor Changes
604
+
605
+ - **Additive: a configuration change invalidates that scope's cached reads.** Correcting a provider document, or adding or editing a goal, used to leave every cached read in place until its TTL ran out, up to an hour on most sources, because only the in-process lookup maps were cleared. Every cache key now carries a per-scope cache epoch, an opaque token kept in `payload.kv`. Saving or deleting a provider document or a goal document bumps the epoch of the scope it belongs to, and of the scope it left when a document moves between scopes, so the next read of that scope misses and asks the source again. Old entries are not deleted; they expire by TTL under keys no read asks for. An instance reads a scope's token at most once every ten seconds, so a change made on one instance reaches the others within ten seconds. A token that cannot be read falls back to `0` with a warning logged once per process, not once per incident, and never fails an analytics read; for that ten second window the instance may serve entries written before the bump it could not see. A bump that fails, or has not settled after two seconds, is logged and dropped rather than failing the save that triggered it; a save that moved a document between scopes bumps both of them under that one two second deadline.
606
+
607
+ **Additive: `POST /api/analytics/refresh` and a Refresh button.** The endpoint bumps one scope's epoch and answers `{ "epoch": "<token>" }`. It takes the same authentication and `access.read` as the read endpoints, and decides scope through the same code the query endpoint reads with, so it refuses every request that endpoint refuses: only a platform reader may name a `scope` in the JSON body, and on a scoped install a request that resolves no scope at all is refused too, both with `400 untrusted_scope`. `scope: "*"` bumps the install-wide epoch, which is what a cross-scope read's entries key on; a tenant's reads key on that tenant's own epoch and are not refreshed by it. A body over 4 KiB answers `413 payload_too_large`. **Breaking for exhaustive switches:** `QueryErrorCode`, exported from `@10x-media/analytics/types`, gains `payload_too_large`, so a `switch` over it with a `never` default needs a new arm. One instance bumps a given scope at most once every five seconds for this endpoint, answering the token already in force inside that window, so a looped call cannot turn a scope's cached reads into provider calls over and over; the document hooks are never debounced. The endpoint is state-changing and cookie-authenticated, so configure Payload's `csrf` allowlist on any install that exposes it. The analytics view's toolbar gains a **Refresh** button that calls it and reissues the cards, trend, breakdown and goals sections; the realtime strip and already-rendered dashboard widgets pick the bump up on their own next read. `refreshCache(apiRoute, { scope, signal })` is exported from `@10x-media/analytics/client` beside `fetchQuery`, with `RefreshRequest` and `RefreshResponse` in `@10x-media/analytics/types`.
608
+
609
+ **Behavioral: the cache key format changed.** Every key now carries the epoch as its second segment, so entries written by the previous release are never read again and every read misses once after the upgrade. Nothing needs to be cleared by hand, and the orphaned entries expire on their own.
610
+
611
+ - **Breaking (contract): `channel` is a new dimension.** `DIMENSION_KEYS` gains `channel`, right after `source`. Code holding an exhaustive `Record<DimensionKey, ...>` needs the new key. `source` and `channel` now mean the same two things on every adapter that serves them: `source` is the visit's named origin (the `utm_source` tag when there is one, otherwise the referrer), and `channel` is the classification of that origin into an acquisition channel, in each source's own vocabulary. `TRAFFIC_CHANNELS` and `TrafficChannel`, exported from `@10x-media/analytics/types`, go from six tokens to twelve, so an exhaustive `Record<TrafficChannel, ...>` needs the new members.
612
+
613
+ **Breaking (native installs): `source` stores the named origin again, and `channel` stores the classification.** The previous release stored one of six channel tokens in `source`. Native now stores `utm_source` lowercased, else the referring host, else the token `direct` in `source`, and one of twelve tokens in the new `channel` column: `direct`, `organic-search`, `paid-search`, `organic-social`, `paid-social`, `organic-video`, `paid-video`, `email`, `affiliate`, `display`, `referral`, `paid-other`. A paid visit is one whose `utm_medium` is `cpc`, `ppc` or starts with `paid`, or whose query carries a Google Ads, Microsoft Ads or TikTok Ads click id (`gclid`, `gbraid`, `wbraid`, `msclkid`, `ttclid`); the platform comes from the referrer host, from `utm_source` by name when there is no referrer host at all, and on the paid path from `utm_source` too when the host names no platform, so an ad click arriving through a network's redirect host keeps its platform. `utm_medium` values `email`, `newsletter`, `affiliate`, `affiliates`, `display`, `banner`, `cpm`, `retargeting`, `remarketing`, `social`, `social-media`, `sm`, `organic` and `search` classify directly. Events also carry `channelVersion`, the version of the rules that classified them, so a later reclassification can find rows written under older rules. The events collection gains the `channel` and `channel_version` columns: Postgres migrate-mode installs add them with the updated snippet in the native docs; Mongo and push-mode installs need nothing. Nothing is backfilled, so rows written by the previous release keep the token they stored in `source`. The `channelSearch`, `channelSocial` and `channelPaid` translation keys are gone, replaced by `channelOrganicSearch` / `channelPaidSearch`, `channelOrganicSocial` / `channelPaidSocial` and `channelPaidOther`; an override of a removed key fails to compile. Because `source` now holds lowercased `utm_source` values (capped at 128 characters), its rollup rows grow with the number of distinct values an install's traffic carries, one row per value per hostname family, where the old six-token set bounded them.
614
+
615
+ **Fixed: `fbclid` no longer reads as paid.** Facebook appends `fbclid` to every outbound link, organic posts included, so the previous release overcounted paid traffic. It is now a social signal only: with no referrer host, and when no `utm_source` names a platform either, it names the social platform inside whichever of the paid or organic branches the other signals chose, so a visit carrying nothing but `fbclid` is organic social.
616
+
617
+ **Fixed: a row with no value reads "Not set" and offers no filter.** A source can answer a row with no value for the dimension it was grouped by, PostHog's empty `$channel_type` for a pageview captured outside a session among them. The bar carried no label, and clicking it built an `eq ''` filter the query endpoint rejects, since a filter value is one character at minimum. Such a row now renders the new translated `valueNotSet` key on every dimension and every source, and is inert in the view's breakdowns while the rows beside it keep their click.
618
+
619
+ **Additive: providers serve `channel` too.** Plausible maps it to `visit:channel`, GA4 to `sessionDefaultChannelGroup`, PostHog to the session's `$channel_type`, and Umami to `/metrics?type=channel`. Each returns its own channel names, rendered as they arrive; native's tokens render through twelve typed `channel*` translations. `channel` is filterable on native, Plausible, GA4 and PostHog, and groupable only on Umami, whose API takes no channel filter.
620
+
621
+ **Behavioral: the Sources tab opens on channels.** The tab's dimensions now lead with `channel`, then `source`, then `referrer` and the campaign keys, so it opens on the channel overview wherever the source serves one; the named origin and the referring host are one pick away in **Group by**. PostHog gains a Sources tab, which it did not have before. An existing link naming `tab=sources` opens on channels unless it also carries `dim`.
622
+
623
+ **Additive: a channels widget.** `analytics-breakdown-channels` ranks channels on the dashboard, opening on visitors, and links into the Sources tab; `analyticsDefaultWidgets()` places it after the sources card. The sources widget keeps ranking `source`.
624
+
625
+ - **Breaking (wire): every endpoint answers errors in one envelope.** The query and refresh endpoints answered `{ "error": { "code", "message", "param"? } }`. The document, sources, goals and native ingest endpoints answered a bare string, `{ "error": "forbidden" }`, and the realtime endpoint answered one shape or the other depending on which failure it hit. All of them now answer the envelope, over one typed code vocabulary. Code that read `error` as a string from any of those endpoints reads `error.code` and `error.message` instead. Status codes are unchanged except on the document endpoint, and no success body changed. The capture proxy stays bodyless and is the one endpoint that sends no envelope: it relays a vendor SDK's own traffic, and that SDK, not admin code, reads the answer.
626
+
627
+ **Breaking (types): the code union gains `not_found`.** It is what the document endpoint answers for a document that is not there or not this caller's to read. `QueryErrorCode` is now an alias of the plugin-wide `AnalyticsErrorCode`, so an exhaustive `switch` over either name stops compiling until it handles the new member. Treat an unrecognized code as a generic failure of its status: the union is open to additions.
628
+
629
+ **Behavioral: the document endpoint no longer hides a broken install as a `404`.** Its catch-all answered `404` for every failure while reading a document. A document that does not exist, one this caller may not read, an unbound collection and a missing `id` are all still a uniform `404 not_found`, so analytics never confirm a document exists; `findByID` failing for any other reason is now a logged `500 internal`.
630
+
631
+ **Behavioral: two answers changed their headers.** The goals endpoint sends `cache-control: private, no-store` on every answer, successful listings included, like every other scope-dependent endpoint whose answer is not cached at all. The document endpoint's `503` now carries `Retry-After: 30`, matching the query endpoint on the same condition. Native ingest refusals carry `no-store` as well, which is harmless on a public endpoint and keeps one builder for every error. The tracker config endpoint is deliberately untouched: it has no failure path to convert, and it keeps `private, max-age=60` with `Vary: Host, Cookie`, the one scope-dependent answer that is cached at all.
632
+
633
+ **Behavioral: the realtime counter stops polling on a refusal aimed at the reader.** A `401 unauthorized` or a `403 forbidden` ends the interval, since no later tick talks its way out of either. An outage, an unreadable body and a body from an older server all keep polling. The counter shows the paused label it always did, so there is no new state and no new string.
634
+
635
+ **Behavioral: `QueryFetchError.error` is undefined for a code this release does not know.** `fetchQuery` and `refreshCache` read the envelope through the same reader the rest of the package uses, so a body carrying a code a newer server added is reported as a generic failure of its status rather than typed as a `QueryErrorCode` it is not. `status` and `retryAfter` are unchanged, and `error` is still set for every code this release defines.
636
+
637
+ **Additive: refusals name the field at fault.** Native ingest puts the first field an event failed on in `param`, checked as `type`, `path`, `hostname`, `name`; unparseable JSON names `type`, and a body that died in transit names nothing. The document endpoint names the custom range bound at fault, `from` or `to`, where it answered `{ "error": "invalid range" }` with nothing to branch on; an inverted window blames `to`.
638
+
639
+ **Additive: `AnalyticsErrorCode`, `AnalyticsError`, `ANALYTICS_ERROR_CODES`, `analyticsError`, `readErrorCode` and `readResponseError`.** `readErrorCode(body)` answers the code of an envelope body and `undefined` for anything else, so admin code branches on a failed answer without parsing it by hand; it is exported from `@10x-media/analytics/client` and `@10x-media/analytics/types`, which both also export the `AnalyticsError` and `AnalyticsErrorCode` types. `readResponseError(res)` is the same read over a `Response` nothing has parsed yet, answering the whole error and `undefined` for a body that is not JSON, an empty and an already-consumed one included, rather than throwing; it is exported from `@10x-media/analytics/client`. `ANALYTICS_ERROR_CODES` is exported from `@10x-media/analytics/types` and the package root, and the builder `analyticsError` from the root. `QueryError` and `QueryErrorCode` stay exported under their own names as aliases.
640
+
641
+ - A native event is attributed to the request that carried it, not to the hostname its body claims.
642
+
643
+ **Breaking:** the hostname a native event is stored under is now the host the request carried (the `x-forwarded-host` entry `n` from the right where `trustedProxyHops` is `n >= 1`, else `Host`), and the body's claim is ignored. The forwarded chain is counted from the trusted end exactly as `x-forwarded-for` is, because a proxy that appends rather than replaces leaves the client's own value at the head of it; a chain shorter than `n`, or an entry that is no hostname, falls back to `Host`, whose peer is the trusted proxy. `Origin` is never read: a scripted client can pair a valid `Host` with any `Origin` and mint unlimited hostname bucket families inside one scope, which is the hole this closes. An install whose beacons already post from the site they are counting sees no change, because the request's host is the page's host; an install whose tracker posts to a different host than the page runs on sees its stored hostname change, and should use the new `hostname` resolver form.
644
+
645
+ **Breaking:** there is now one definition of a hostname, and config entries, the request host, a resolver's answer and a form goal action's host are all held to it. A value is lowercased and loses its port, its brackets and every trailing root dot, and must then be dot-separated labels of `a-z`, `0-9`, `_` and `-` (every IPv4 literal included) or an IPv6 literal of hex groups and colons, within 253 characters. `example.com.`, `example.com..` and `Example.COM:3000` are therefore one hostname rather than four bucket families, `[::1]:3000` is stored as `::1` rather than `[::1]`, and a name over 253 characters is refused instead of truncated into a name of its own. Anything else (a leading or doubled dot, an unclosed bracket, a percent-encoded or non-ASCII spelling, a non-numeric port, a scheme) drops the event.
646
+
647
+ **Breaking:** on an install with a `scopeResolver`, an event whose request resolves no scope is dropped instead of being stored install-wide, unless its resolved hostname is listed in the native adapter's `platformHostnames`. A dropped event answers exactly what an accepted one answers, `202` with `{ ok: true }`, and nothing per event is logged, so the endpoint is no oracle for which hosts or tenants exist.
648
+
649
+ **Behavioral:** the first drop of each reason writes one `warn` line, naming the `scopeResolver` or the `hostname` option to look at, and every later drop of that reason is silent for the life of the process. A public endpoint must not be a log amplifier, since an attacker would otherwise choose how much it writes, but a misconfigured resolver discarding all traffic should not be invisible either.
650
+
651
+ **Breaking:** the ingest body's `hostname` is optional, and a body carrying one is only type-checked. A missing `hostname` no longer answers `400`; a non-string one still does. `trackServerEvent` is unaffected and still requires its own, since trusted server code has no request to attribute an event to.
652
+
653
+ **Additive:** `native({ hostname })` takes `'request'` (the default), a list of hostnames (the request host is stored only when the list holds it, and this is the form to use on a single-site install with no `scopeResolver` and no edge validating `Host`), or an `EventHostnameResolver`, `({ claimed, req, scope }) => string | null`, that decides per event, where `null` drops it and a throw drops it too. It is named apart from the binding `HostnameResolver`, which names the hostname a document is read under. A resolver's answer must itself be a hostname: an id, a slug or a label drops the event rather than being stored as free text per event. List entries are validated at boot: a scheme or a port in an entry, or an empty list, fails the boot rather than silently dropping every event.
654
+
655
+ **Additive:** `native({ platformHostnames })` names the platform's own domains on a scoped install, which ingest under the null scope rather than being dropped. The list is static on purpose: those domains change with a deploy, not with a signup. Tenant domains never belong in it, because a tenant's custom domain is tracked the moment its document is saved, through the install's own `scopeResolver`.
656
+
657
+ **Additive:** `analytics({ trustedProxyHops })` sets how many proxies in front of the app are trusted, counted from the right of `x-forwarded-for`. It is plugin-level because one helper reads the client address for the native visitor hash, for geo, and for the capture proxy's upstream `X-Forwarded-For`. Unset keeps today's leftmost entry, which is correct for honest traffic and client-writable otherwise. At `n >= 1` the forwarded chain is the only source, and a chain shorter than `n` yields no address rather than falling back to the client-writable `x-real-ip`. There is no default of `1`: an install behind a CDN plus a proxy would then read the CDN's address for every visitor, collapsing geo and the visitor hash onto one value.
658
+
659
+ **Additive:** `GeoResolver` gained an optional second argument carrying `trustedProxyHops`, so a resolver that does its own IP lookup reads the same address the rest of the pipeline does. `maxmindResolver` honors it. A one-argument resolver still type-checks and still runs. `GeoResolverOptions`, the type of that argument, is exported from `@10x-media/analytics/geo` beside `GeoResolver`.
660
+
661
+ **Behavioral:** a binding's `hostname` is reduced to the bare lowercased host before it reaches an adapter query, so a tenant domain stored as `https://Example.com/` or with a port still matches the hostnames the native engine writes, which are compared exactly. A value that is no hostname at all reaches the adapter unchanged.
662
+
663
+ **Breaking:** `trackGoalAction` no longer stores the submitting request's `Host` as given. It resolves the `hostname` option first, then that request under the native adapter's own `hostname` policy (so a forged host the ingest endpoint would refuse is refused here too), then the host of `serverURL`. The scoped-install drop rule does not apply, since a submission's scope comes from the form document. With none of the three (no `serverURL`, and a request with no usable host), the completion is not recorded at all: the action writes one `warn` line for the life of the process and returns, rather than throwing inside a submission it is not essential to. The policy is read off the very adapter the event would be written through, so one adapter cannot judge a hostname another one stores. `trackServerEvent` called directly by server code is unchanged: it is trusted, supplies its own hostname, and still requires one.
664
+
665
+ **Additive:** an adapter's `ingest` seam may expose `hostname`, which applies that adapter's own hostname policy to a request. The native adapter provides it, and it is how the form goal action attributes exactly as the endpoint does.
666
+
667
+ **Behavioral:** an existing single-site install sees the same hostname it saw before in the common same-origin case, since the request's host is the page's host there. The visitor hash and the same-site referral check both key off the resolved hostname rather than the claimed one, so a forged body no longer splits one visitor across hostname buckets. The salt, timezone and goal resolvers now run only for an event that will be kept.
668
+
669
+ Rate limiting is deliberately not part of this. The plugin decides what one accepted request may write; how many requests are accepted belongs to the edge, where a per-IP limit can throttle an abuser instead of the whole install's traffic.
670
+
671
+ - Staff can take themselves out of the numbers with a link, and the docs say what a stored event holds.
672
+
673
+ **Additive:** any page opened with `?analytics_exclude=1` takes that browser out of capture, and `=0` puts it back (`true` and `false` work too). The tracker reads the parameter on boot and leaves the URL alone. While the flag is set nothing is delivered to any sink, nothing is queued for a pending consent decision, and no vendor script is injected even after consent is granted; clearing resumes from that point and replays nothing that was skipped. The flag lives in `localStorage` under `analytics:exclude`, so it is per browser and per site, and a browser with storage blocked is excluded for the page the link was opened on and no further, without throwing.
674
+
675
+ **Additive:** `exclusionParam` on `createTracker`/`initTracker` options, beside `persistConsent`. A string renames the parameter, `false` ignores it while still honouring a flag an earlier visit set. Default `analytics_exclude`.
676
+
677
+ **Additive:** `tracker.exclude(next)` and the read-only `tracker.excluded` on the `Tracker` interface, `setExcluded` and `excluded` on `useAnalytics()`, and `EXCLUSION_STORAGE_KEY`, `DEFAULT_EXCLUSION_PARAM`, `readExclusion`, `writeExclusion`, `readExclusionParam` and `subscribeExclusion` from `@10x-media/analytics/tracker`, for a host rendering its own switch. `AnalyticsApi` gains the `excluded` flag and is now `AnalyticsCommands` (the imperative half, also exported from `@10x-media/analytics/react`) plus that flag; nothing was removed from it, and the React context itself is not part of the package's export surface.
678
+
679
+ **Additive:** the vendor sinks expose their own opt-out through the optional `Sink.exclude`, with `PLAUSIBLE_IGNORE_KEY`, `UMAMI_DISABLED_KEY`, `GA4_DISABLE_PREFIX` and `Ga4SinkArgs` exported alongside them.
680
+
681
+ **Behavioral:** a visitor who arrives with the parameter is excluded from then on in that browser, and the exclusion is mirrored into each vendor's own switch for the slots the config has: `plausible_ignore`, `umami.disabled`, PostHog's `opt_out_capturing()` and GA4's `ga-disable-<measurementId>`. A snippet the server rendered for a slot that does not require consent runs before the tracker boots, so that vendor's own page view for the page the link was opened on may already have been sent; Plausible, Umami and PostHog persist their switch and are silent from the next load. GA4's is a window property that does not persist and counts only ahead of the first `gtag()` call, so the rendered GA4 snippet reads `analytics:exclude` itself and sets the switch before its own `gtag('config', ...)`: the page the link is opened on may still be measured, and from the next page load on nothing is. A gated slot, which is GA4's default, never loads while the browser is excluded. A vendor key the tracker did not set is cleared only by an explicit `=0` or `exclude(false)`, so one a staff member set by hand survives an ordinary visit; an explicit clear does clear it, which is the cost of off meaning off.
682
+
683
+ **Breaking (types only):** the exported `Tracker` type gains two required members, `excluded` and `exclude`. Code that implements `Tracker` itself, such as a test double or a wrapper, has to add them. The same holds for `AnalyticsApi`, the return type of `useAnalytics()`, which gains a required `excluded`: a hand-built value of that type, such as a mocked hook in a test, has to add it. Callers are unaffected.
684
+
685
+ **Behavioral:** the tracker's built entry grows by about 6 KB unminified. It stays dependency-free.
686
+
687
+ **Additive:** a Privacy page in the docs states, column by column, what a stored native event holds and where each value comes from, that no cookie is set and which `localStorage` keys exist, how the daily-salted visitor hash works and why two days cannot be joined once its salt is swept, that the client address is used for the hash and geo and stored nowhere, that the raw query string is read for the campaign keys and the ad click ids and then discarded, what a `path` or a prop the site authors can therefore carry, and what an access or erasure request can and cannot find. It states facts about the code and makes no legal claim. Capture documents the exclusion link beside it, including what a link carrying the parameter costs when anyone sends one to a real visitor.
688
+
689
+ - Everything the native engine stores has an end, and automated traffic does not count.
690
+
691
+ **Behavioral:** crawlers, link-preview fetchers, monitors and headless clients are dropped at ingest by default, decided from the request's `user-agent` before the body is read. A dropped beacon answers exactly what a kept one answers, `202` with `{ ok: true }` and the same headers, and a recognized marker logs nothing at all: automated traffic is expected on a public endpoint rather than a misconfiguration to report. An empty or absent agent counts as automated, since every real browser sends one. Native numbers therefore fall on upgrade, to what real visitors did, with the `other` bucket of the `browser` breakdown dropping the most; nothing is backfilled, so a range spanning the upgrade mixes filtered days with unfiltered ones. `trackServerEvent` writes through its own path and is never filtered, whatever agent it attributes the event to.
692
+
693
+ **Behavioral:** the nightly prune task (`analytics-prune-events`) is registered only on an install that sets `retentionDays` or the new `rollupRetentionDays`, and it sweeps the daily visitor salts as well as the collections whenever it runs. An install that sets neither registers no task, so it gains no jobs config it did not ask for. Setting a window on an install that had no tasks or workflows at all does give it Payload's `payload-jobs` collection and, for a scheduled task, the `payload-jobs-stats` global: push-mode installs pick the tables up on the next boot, and a migrate-mode Postgres install creates them in a migration, the same as for any other new collection. That was already true of `retentionDays` before this release and is unchanged by it.
694
+
695
+ **Additive:** `native({ rollupRetentionDays })` deletes rollup rows whose `period` is older than the window. Off by default, because rollups are the long-term store and an unfiltered day-granularity read is served from them alone. It takes a whole number of days above zero, requires `retentionDays`, and may not be shorter than it; both rules fail the boot rather than the sweep. Pruning rollups while keeping raw events forever would make an unfiltered long window answer less than the same window filtered, and a shorter rollup window would make a two-year report show less than a three-month one. Once a rollup row is pruned, the day it covered reports nothing rather than falling back to raw events. `retentionDays` itself is otherwise unchanged, including that zero or less still means keep everything; a value above zero now goes through the same check as the rollup window, so a window that is not a whole number of days, `Infinity` among them, fails the boot rather than the first nightly run.
696
+
697
+ **Additive:** `native({ filterBots })` takes `false` to count every beacon, or a `(ua: string) => boolean` predicate that replaces the built-in rule rather than extending it. A predicate that throws keeps the event and warns once per process, naming `filterBots`: a broken filter must not discard a site's traffic, and it must not do it in silence either.
698
+
699
+ **Additive:** a beacon that arrives with no user agent at all is dropped like any other automated traffic, and warns once per process that an intermediary may be stripping the header. A proxy that strips it would otherwise take an install's numbers to zero with nothing in the log to look at, while a recognized marker stays silent.
700
+
701
+ **Additive:** `isBot` and the `BotFilter` type are exported from `@10x-media/analytics/adapters/native`, so the same rule can run in an install's own middleware or edge config, or be composed with a filter of its own. It matches a small hand-held set of lowercase substrings anywhere in the agent, covering crawlers, link-preview fetchers, monitors and audits, headless and automation drivers, and the default agents of HTTP libraries; the docs table lists the families, and the set itself is deliberately not exported. There is no third-party list and no new dependency. Matching mid-word is what makes `bot` cover `Googlebot` and `AhrefsBot` without an entry each, so `Cubot` handset models are stripped from the agent before the scan and a Cubot phone stays a visitor.
702
+
703
+ **Fixed:** the daily visitor salts in `payload.kv` accumulated forever, one key per UTC day, with nothing ever deleting one. A first event of a new UTC day now deletes the seven days before the two most recent, at ingest, fire and forget, so no install needs a jobs runner to stop them piling up; the nightly task sweeps the days 2 to 62 back when it runs. Today's and yesterday's are always kept, since an event arriving just before midnight is still hashed with yesterday's. Keys are deleted by computed name rather than by listing them, so a sweep costs no scan, works on every kv adapter, and a day already gone is a no-op. An install down for longer than 62 days keeps the salts older than that, inert and one small value per day.
704
+
705
+ **Fixed:** the prune loaded every document it deleted. Deletes now go through the database adapter's bulk delete, so nothing is read in order to be removed, whatever the window matches. Collection hooks and access control are bypassed by a database-level delete, and the three collections involved use neither.
706
+
707
+ **Behavioral:** the prune task's output is consequently `{}` rather than `{ deleted: number }`, a shape change for anyone reading a job result: a count would cost exactly the read the bulk delete avoids.
708
+
709
+ ### Patch Changes
710
+
711
+ - **Fixed: scroll depth read from raw events no longer collapses on Postgres.** The raw-event path (an hourly series, and any filtered read that bypasses the rollups) counted one scroll sample per event whenever the driver returned an unreported depth as `null` rather than omitting the field, which Postgres does for every event that carried no depth. The average was then divided by every event in range instead of by the pageviews that actually reported a depth, so a site whose tracker reports depth on a fraction of its pageviews saw a scroll depth several times too low on Postgres while the rollup-backed reads of the same range showed the right number. Only a depth that is a number counts as a sample now, on both adapters, and a reported `0` still counts.
712
+
3
713
  ## 1.0.0-beta.9
4
714
 
5
715
  ### Minor Changes