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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (515) hide show
  1. package/CHANGELOG.md +270 -0
  2. package/LICENSE +21 -21
  3. package/README.md +15 -4
  4. package/dist/adapters/ga4/disableKey.d.ts +9 -0
  5. package/dist/adapters/ga4/disableKey.js +21 -0
  6. package/dist/adapters/ga4/disableKey.js.map +1 -0
  7. package/dist/adapters/ga4/eventName.d.ts +15 -0
  8. package/dist/adapters/ga4/eventName.js +19 -0
  9. package/dist/adapters/ga4/eventName.js.map +1 -0
  10. package/dist/adapters/ga4/ga4.d.ts +5 -0
  11. package/dist/adapters/ga4/ga4.js +186 -58
  12. package/dist/adapters/ga4/ga4.js.map +1 -1
  13. package/dist/adapters/ga4/measurementId.js +15 -0
  14. package/dist/adapters/ga4/measurementId.js.map +1 -0
  15. package/dist/adapters/goalRead.js +126 -0
  16. package/dist/adapters/goalRead.js.map +1 -0
  17. package/dist/adapters/http/fetchJson.js +1 -1
  18. package/dist/adapters/plausible/plausible.d.ts +25 -0
  19. package/dist/adapters/plausible/plausible.js +159 -38
  20. package/dist/adapters/plausible/plausible.js.map +1 -1
  21. package/dist/adapters/posthog/posthog.d.ts +10 -1
  22. package/dist/adapters/posthog/posthog.js +130 -21
  23. package/dist/adapters/posthog/posthog.js.map +1 -1
  24. package/dist/adapters/series.js +11 -1
  25. package/dist/adapters/series.js.map +1 -1
  26. package/dist/adapters/umami/umami.d.ts +13 -1
  27. package/dist/adapters/umami/umami.js +278 -26
  28. package/dist/adapters/umami/umami.js.map +1 -1
  29. package/dist/binding/resolvePath.js +18 -2
  30. package/dist/binding/resolvePath.js.map +1 -1
  31. package/dist/capture/getTrackerConfig.d.ts +20 -0
  32. package/dist/capture/getTrackerConfig.js +31 -0
  33. package/dist/capture/getTrackerConfig.js.map +1 -0
  34. package/dist/capture/mountPath.js +14 -0
  35. package/dist/capture/mountPath.js.map +1 -0
  36. package/dist/capture/proxyEndpoint.js +127 -0
  37. package/dist/capture/proxyEndpoint.js.map +1 -0
  38. package/dist/capture/proxyRoutes.js +108 -0
  39. package/dist/capture/proxyRoutes.js.map +1 -0
  40. package/dist/capture/requestBody.js +68 -0
  41. package/dist/capture/requestBody.js.map +1 -0
  42. package/dist/capture/slots.d.ts +8 -0
  43. package/dist/capture/slots.js +54 -0
  44. package/dist/capture/slots.js.map +1 -0
  45. package/dist/capture/trackerConfig.d.ts +33 -0
  46. package/dist/capture/trackerConfig.js +95 -0
  47. package/dist/capture/trackerConfig.js.map +1 -0
  48. package/dist/capture/trackerEndpoint.js +35 -0
  49. package/dist/capture/trackerEndpoint.js.map +1 -0
  50. package/dist/charts/BarList.d.ts +16 -1
  51. package/dist/charts/BarList.js +41 -19
  52. package/dist/charts/BarList.js.map +1 -1
  53. package/dist/charts/TrendChart.d.ts +16 -3
  54. package/dist/charts/TrendChart.js +172 -106
  55. package/dist/charts/TrendChart.js.map +1 -1
  56. package/dist/charts/bars.d.ts +4 -0
  57. package/dist/charts/bars.js +3 -1
  58. package/dist/charts/bars.js.map +1 -1
  59. package/dist/charts/bucket.js +10 -1
  60. package/dist/charts/bucket.js.map +1 -1
  61. package/dist/charts/spline.js +2 -2
  62. package/dist/charts/spline.js.map +1 -1
  63. package/dist/charts/styles.js +18 -1
  64. package/dist/charts/styles.js.map +1 -1
  65. package/dist/core/cacheKey.js +26 -3
  66. package/dist/core/cacheKey.js.map +1 -1
  67. package/dist/core/capabilities.d.ts +5 -1
  68. package/dist/core/capabilities.js +11 -2
  69. package/dist/core/capabilities.js.map +1 -1
  70. package/dist/core/capture.d.ts +49 -0
  71. package/dist/core/contract.d.ts +74 -5
  72. package/dist/core/contract.js +30 -1
  73. package/dist/core/contract.js.map +1 -1
  74. package/dist/core/granularity.js +1 -1
  75. package/dist/core/options.d.ts +164 -6
  76. package/dist/core/options.js +126 -3
  77. package/dist/core/options.js.map +1 -1
  78. package/dist/core/registry.d.ts +1 -0
  79. package/dist/core/scopeList.js +32 -0
  80. package/dist/core/scopeList.js.map +1 -0
  81. package/dist/core/scopedRead.js +101 -30
  82. package/dist/core/scopedRead.js.map +1 -1
  83. package/dist/core/serverEvent.d.ts +60 -0
  84. package/dist/core/serverEvent.js +12 -0
  85. package/dist/core/serverEvent.js.map +1 -0
  86. package/dist/exports/adapters/ga4.d.ts +2 -1
  87. package/dist/exports/adapters/ga4.js +2 -1
  88. package/dist/exports/adapters/native.d.ts +3 -1
  89. package/dist/exports/adapters/native.js +2 -1
  90. package/dist/exports/client.d.ts +13 -3
  91. package/dist/exports/client.js +10 -1
  92. package/dist/exports/geo.d.ts +2 -2
  93. package/dist/exports/next.d.ts +2 -1
  94. package/dist/exports/next.js +2 -1
  95. package/dist/exports/react.d.ts +4 -0
  96. package/dist/exports/react.js +5 -0
  97. package/dist/exports/rsc.d.ts +11 -3
  98. package/dist/exports/rsc.js +7 -2
  99. package/dist/exports/tracker.d.ts +21 -0
  100. package/dist/exports/tracker.js +15 -0
  101. package/dist/exports/types.d.ts +16 -3
  102. package/dist/exports/types.js +4 -2
  103. package/dist/fields/AnalyticsPanelClient.js +2 -2
  104. package/dist/fields/AnalyticsPanelField.js +1 -1
  105. package/dist/fields/AnalyticsStatField.js +2 -2
  106. package/dist/fields/config/FilterDimensionSelectField.d.ts +14 -0
  107. package/dist/fields/config/FilterDimensionSelectField.js +77 -0
  108. package/dist/fields/config/FilterDimensionSelectField.js.map +1 -0
  109. package/dist/fields/config/FilterOperatorSelectField.d.ts +14 -0
  110. package/dist/fields/config/FilterOperatorSelectField.js +75 -0
  111. package/dist/fields/config/FilterOperatorSelectField.js.map +1 -0
  112. package/dist/fields/config/MetricSelectField.js +3 -3
  113. package/dist/fields/config/MetricSelectField.js.map +1 -1
  114. package/dist/fields/config/SourceSelectField.js +3 -3
  115. package/dist/fields/config/SourceSelectField.js.map +1 -1
  116. package/dist/fields/config/fetchSources.d.ts +5 -1
  117. package/dist/fields/config/fetchSources.js +7 -3
  118. package/dist/fields/config/fetchSources.js.map +1 -1
  119. package/dist/fields/config/narrow.js +2 -0
  120. package/dist/fields/config/narrow.js.map +1 -1
  121. package/dist/fields/config/sourcesState.js +19 -3
  122. package/dist/fields/config/sourcesState.js.map +1 -1
  123. package/dist/fields/config/useAnalyticsSources.d.ts +8 -3
  124. package/dist/fields/config/useAnalyticsSources.js +9 -6
  125. package/dist/fields/config/useAnalyticsSources.js.map +1 -1
  126. package/dist/fields/config/useFilterCapabilities.d.ts +28 -0
  127. package/dist/fields/config/useFilterCapabilities.js +52 -0
  128. package/dist/fields/config/useFilterCapabilities.js.map +1 -0
  129. package/dist/fields/readForDocument.d.ts +5 -0
  130. package/dist/fields/readForDocument.js +22 -10
  131. package/dist/fields/readForDocument.js.map +1 -1
  132. package/dist/goals/GoalSelectField.d.ts +7 -0
  133. package/dist/goals/GoalSelectField.js +77 -0
  134. package/dist/goals/GoalSelectField.js.map +1 -0
  135. package/dist/goals/collection.js +254 -0
  136. package/dist/goals/collection.js.map +1 -0
  137. package/dist/goals/currency.js +14 -0
  138. package/dist/goals/currency.js.map +1 -0
  139. package/dist/goals/fetchGoals.d.ts +18 -0
  140. package/dist/goals/fetchGoals.js +33 -0
  141. package/dist/goals/fetchGoals.js.map +1 -0
  142. package/dist/goals/goalField.d.ts +31 -0
  143. package/dist/goals/goalField.js +56 -0
  144. package/dist/goals/goalField.js.map +1 -0
  145. package/dist/goals/goalsEndpoint.d.ts +1 -0
  146. package/dist/goals/goalsEndpoint.js +58 -0
  147. package/dist/goals/goalsEndpoint.js.map +1 -0
  148. package/dist/goals/match.js +64 -0
  149. package/dist/goals/match.js.map +1 -0
  150. package/dist/goals/resolver.d.ts +8 -0
  151. package/dist/goals/resolver.js +147 -0
  152. package/dist/goals/resolver.js.map +1 -0
  153. package/dist/goals/trackGoalAction.d.ts +76 -0
  154. package/dist/goals/trackGoalAction.js +158 -0
  155. package/dist/goals/trackGoalAction.js.map +1 -0
  156. package/dist/goals/types.d.ts +33 -0
  157. package/dist/goals/types.js +7 -0
  158. package/dist/goals/types.js.map +1 -0
  159. package/dist/goals/useAnalyticsGoals.d.ts +20 -0
  160. package/dist/goals/useAnalyticsGoals.js +67 -0
  161. package/dist/goals/useAnalyticsGoals.js.map +1 -0
  162. package/dist/index.d.ts +14 -3
  163. package/dist/index.js +174 -19
  164. package/dist/index.js.map +1 -1
  165. package/dist/native/collections/events.js +65 -1
  166. package/dist/native/collections/events.js.map +1 -1
  167. package/dist/native/collections/rollups.js +39 -3
  168. package/dist/native/collections/rollups.js.map +1 -1
  169. package/dist/native/eventScan.js +25 -0
  170. package/dist/native/eventScan.js.map +1 -0
  171. package/dist/native/geo/composeGeoResolvers.js +2 -2
  172. package/dist/native/geo/composeGeoResolvers.js.map +1 -1
  173. package/dist/native/geo/geoResolver.d.ts +9 -2
  174. package/dist/native/geo/geoResolver.js.map +1 -1
  175. package/dist/native/geo/maxmindResolver.js +3 -5
  176. package/dist/native/geo/maxmindResolver.js.map +1 -1
  177. package/dist/native/ingest/bots.d.ts +11 -0
  178. package/dist/native/ingest/bots.js +71 -0
  179. package/dist/native/ingest/bots.js.map +1 -0
  180. package/dist/native/ingest/browser.js +47 -0
  181. package/dist/native/ingest/browser.js.map +1 -0
  182. package/dist/native/ingest/clientIp.js +20 -0
  183. package/dist/native/ingest/clientIp.js.map +1 -0
  184. package/dist/native/ingest/device.js +11 -3
  185. package/dist/native/ingest/device.js.map +1 -1
  186. package/dist/native/ingest/endpoint.d.ts +1 -0
  187. package/dist/native/ingest/endpoint.js +107 -21
  188. package/dist/native/ingest/endpoint.js.map +1 -1
  189. package/dist/native/ingest/flushBatch.js +29 -38
  190. package/dist/native/ingest/flushBatch.js.map +1 -1
  191. package/dist/native/ingest/language.js +14 -0
  192. package/dist/native/ingest/language.js.map +1 -0
  193. package/dist/native/ingest/normalizeEvent.d.ts +30 -0
  194. package/dist/native/ingest/normalizeEvent.js +115 -16
  195. package/dist/native/ingest/normalizeEvent.js.map +1 -1
  196. package/dist/native/ingest/referrer.js +48 -0
  197. package/dist/native/ingest/referrer.js.map +1 -0
  198. package/dist/native/ingest/requestHost.js +57 -0
  199. package/dist/native/ingest/requestHost.js.map +1 -0
  200. package/dist/native/ingest/resolveHostname.d.ts +29 -0
  201. package/dist/native/ingest/resolveHostname.js +52 -0
  202. package/dist/native/ingest/resolveHostname.js.map +1 -0
  203. package/dist/native/ingest/salt.js +27 -2
  204. package/dist/native/ingest/salt.js.map +1 -1
  205. package/dist/native/ingest/serverTrack.d.ts +20 -0
  206. package/dist/native/ingest/serverTrack.js +109 -0
  207. package/dist/native/ingest/serverTrack.js.map +1 -0
  208. package/dist/native/ingest/source.d.ts +11 -0
  209. package/dist/native/ingest/source.js +264 -16
  210. package/dist/native/ingest/source.js.map +1 -1
  211. package/dist/native/ingest/utm.js +33 -0
  212. package/dist/native/ingest/utm.js.map +1 -0
  213. package/dist/native/ingest/validate.js +26 -0
  214. package/dist/native/ingest/validate.js.map +1 -0
  215. package/dist/native/nativeAdapter.d.ts +37 -1
  216. package/dist/native/nativeAdapter.js +175 -22
  217. package/dist/native/nativeAdapter.js.map +1 -1
  218. package/dist/native/query/eventAgg.js +175 -0
  219. package/dist/native/query/eventAgg.js.map +1 -0
  220. package/dist/native/retention/pruneTask.js +53 -13
  221. package/dist/native/retention/pruneTask.js.map +1 -1
  222. package/dist/native/rollupAcc.js +12 -1
  223. package/dist/native/rollupAcc.js.map +1 -1
  224. package/dist/native/rollups/bucketKey.js +15 -0
  225. package/dist/native/rollups/bucketKey.js.map +1 -0
  226. package/dist/native/rollups/bumpRollups.js +116 -0
  227. package/dist/native/rollups/bumpRollups.js.map +1 -0
  228. package/dist/native/rollups/deltas.js +86 -11
  229. package/dist/native/rollups/deltas.js.map +1 -1
  230. package/dist/native/rollups/insertManyIfNew.js +93 -0
  231. package/dist/native/rollups/insertManyIfNew.js.map +1 -0
  232. package/dist/next/captureRewrites.d.ts +42 -0
  233. package/dist/next/captureRewrites.js +57 -0
  234. package/dist/next/captureRewrites.js.map +1 -0
  235. package/dist/next/posthogProxyRewrites.d.ts +5 -0
  236. package/dist/next/posthogProxyRewrites.js +16 -21
  237. package/dist/next/posthogProxyRewrites.js.map +1 -1
  238. package/dist/plugin/documentEndpoint.js +71 -24
  239. package/dist/plugin/documentEndpoint.js.map +1 -1
  240. package/dist/plugin/errors.d.ts +31 -0
  241. package/dist/plugin/errors.js +79 -0
  242. package/dist/plugin/errors.js.map +1 -0
  243. package/dist/plugin/goalHint.d.ts +1 -0
  244. package/dist/plugin/goalHint.js +24 -0
  245. package/dist/plugin/goalHint.js.map +1 -0
  246. package/dist/plugin/paths.js +17 -1
  247. package/dist/plugin/paths.js.map +1 -1
  248. package/dist/plugin/queryEndpoint.js +124 -0
  249. package/dist/plugin/queryEndpoint.js.map +1 -0
  250. package/dist/plugin/readContextForRequest.js +73 -0
  251. package/dist/plugin/readContextForRequest.js.map +1 -0
  252. package/dist/plugin/realtimeEndpoint.js +37 -16
  253. package/dist/plugin/realtimeEndpoint.js.map +1 -1
  254. package/dist/plugin/refreshEndpoint.js +113 -0
  255. package/dist/plugin/refreshEndpoint.js.map +1 -0
  256. package/dist/plugin/runtime.d.ts +1 -0
  257. package/dist/plugin/runtime.js +33 -1
  258. package/dist/plugin/runtime.js.map +1 -1
  259. package/dist/plugin/scopeChange.js +22 -0
  260. package/dist/plugin/scopeChange.js.map +1 -0
  261. package/dist/plugin/scopeFieldBoot.js +22 -0
  262. package/dist/plugin/scopeFieldBoot.js.map +1 -0
  263. package/dist/plugin/sourcesEndpoint.js +16 -41
  264. package/dist/plugin/sourcesEndpoint.js.map +1 -1
  265. package/dist/plugin/warmTask.js +0 -0
  266. package/dist/plugin/warmTask.js.map +1 -1
  267. package/dist/providers/collection.js +89 -29
  268. package/dist/providers/collection.js.map +1 -1
  269. package/dist/providers/factory.js +11 -3
  270. package/dist/providers/factory.js.map +1 -1
  271. package/dist/providers/resolver.js.map +1 -1
  272. package/dist/query/dates.js +64 -0
  273. package/dist/query/dates.js.map +1 -0
  274. package/dist/query/errors.d.ts +14 -0
  275. package/dist/query/fetchQuery.d.ts +79 -0
  276. package/dist/query/fetchQuery.js +117 -0
  277. package/dist/query/fetchQuery.js.map +1 -0
  278. package/dist/query/parse.d.ts +22 -0
  279. package/dist/query/parse.js +168 -0
  280. package/dist/query/parse.js.map +1 -0
  281. package/dist/query/response.d.ts +39 -0
  282. package/dist/query/response.js +11 -0
  283. package/dist/query/response.js.map +1 -0
  284. package/dist/react/AnalyticsProvider.d.ts +50 -0
  285. package/dist/react/AnalyticsProvider.js +67 -0
  286. package/dist/react/AnalyticsProvider.js.map +1 -0
  287. package/dist/react/TrackerBoot.d.ts +22 -0
  288. package/dist/react/TrackerBoot.js +30 -0
  289. package/dist/react/TrackerBoot.js.map +1 -0
  290. package/dist/react/useAnalytics.d.ts +20 -0
  291. package/dist/react/useAnalytics.js +52 -0
  292. package/dist/react/useAnalytics.js.map +1 -0
  293. package/dist/rsc/AnalyticsScripts.d.ts +30 -0
  294. package/dist/rsc/AnalyticsScripts.js +41 -0
  295. package/dist/rsc/AnalyticsScripts.js.map +1 -0
  296. package/dist/surfacing/cacheStore.d.ts +1 -0
  297. package/dist/surfacing/cacheStore.js +18 -2
  298. package/dist/surfacing/cacheStore.js.map +1 -1
  299. package/dist/surfacing/engine.d.ts +1 -0
  300. package/dist/surfacing/engine.js +47 -6
  301. package/dist/surfacing/engine.js.map +1 -1
  302. package/dist/surfacing/epoch.d.ts +1 -0
  303. package/dist/surfacing/epoch.js +72 -0
  304. package/dist/surfacing/epoch.js.map +1 -0
  305. package/dist/surfacing/queue.js +22 -6
  306. package/dist/surfacing/queue.js.map +1 -1
  307. package/dist/surfacing/rateLimiter.js +130 -0
  308. package/dist/surfacing/rateLimiter.js.map +1 -0
  309. package/dist/surfacing/retryPolicy.js +15 -0
  310. package/dist/surfacing/retryPolicy.js.map +1 -0
  311. package/dist/sync/collection.js +23 -7
  312. package/dist/sync/collection.js.map +1 -1
  313. package/dist/sync/syncTask.js +68 -33
  314. package/dist/sync/syncTask.js.map +1 -1
  315. package/dist/testing/memoryAdapter.d.ts +2 -0
  316. package/dist/testing/memoryAdapter.js +17 -1
  317. package/dist/testing/memoryAdapter.js.map +1 -1
  318. package/dist/timeframe/tz.js +17 -6
  319. package/dist/timeframe/tz.js.map +1 -1
  320. package/dist/tracker/autoCapture.d.ts +48 -0
  321. package/dist/tracker/autoCapture.js +129 -0
  322. package/dist/tracker/autoCapture.js.map +1 -0
  323. package/dist/tracker/consent.d.ts +24 -0
  324. package/dist/tracker/consent.js +48 -0
  325. package/dist/tracker/consent.js.map +1 -0
  326. package/dist/tracker/createTracker.d.ts +18 -0
  327. package/dist/tracker/createTracker.js +215 -0
  328. package/dist/tracker/createTracker.js.map +1 -0
  329. package/dist/tracker/exclusion.d.ts +28 -0
  330. package/dist/tracker/exclusion.js +50 -0
  331. package/dist/tracker/exclusion.js.map +1 -0
  332. package/dist/tracker/initTracker.d.ts +22 -0
  333. package/dist/tracker/initTracker.js +33 -0
  334. package/dist/tracker/initTracker.js.map +1 -0
  335. package/dist/tracker/loadScript.d.ts +14 -0
  336. package/dist/tracker/loadScript.js +41 -0
  337. package/dist/tracker/loadScript.js.map +1 -0
  338. package/dist/tracker/pageTracking.d.ts +17 -0
  339. package/dist/tracker/pageTracking.js +38 -0
  340. package/dist/tracker/pageTracking.js.map +1 -0
  341. package/dist/tracker/registry.d.ts +27 -0
  342. package/dist/tracker/registry.js +73 -0
  343. package/dist/tracker/registry.js.map +1 -0
  344. package/dist/tracker/sinks/ga4.d.ts +29 -0
  345. package/dist/tracker/sinks/ga4.js +30 -0
  346. package/dist/tracker/sinks/ga4.js.map +1 -0
  347. package/dist/tracker/sinks/native.d.ts +22 -0
  348. package/dist/tracker/sinks/native.js +56 -0
  349. package/dist/tracker/sinks/native.js.map +1 -0
  350. package/dist/tracker/sinks/plausible.d.ts +20 -0
  351. package/dist/tracker/sinks/plausible.js +32 -0
  352. package/dist/tracker/sinks/plausible.js.map +1 -0
  353. package/dist/tracker/sinks/posthog.d.ts +18 -0
  354. package/dist/tracker/sinks/posthog.js +30 -0
  355. package/dist/tracker/sinks/posthog.js.map +1 -0
  356. package/dist/tracker/sinks/umami.d.ts +18 -0
  357. package/dist/tracker/sinks/umami.js +23 -0
  358. package/dist/tracker/sinks/umami.js.map +1 -0
  359. package/dist/tracker/sinks/vendor.d.ts +14 -0
  360. package/dist/tracker/sinks/vendor.js +81 -0
  361. package/dist/tracker/sinks/vendor.js.map +1 -0
  362. package/dist/tracker/transport.js +28 -0
  363. package/dist/tracker/transport.js.map +1 -0
  364. package/dist/tracker/types.d.ts +91 -0
  365. package/dist/translations/ar.js +221 -0
  366. package/dist/translations/ar.js.map +1 -0
  367. package/dist/translations/de.js +145 -1
  368. package/dist/translations/de.js.map +1 -1
  369. package/dist/translations/en.js +145 -1
  370. package/dist/translations/en.js.map +1 -1
  371. package/dist/translations/es.js +221 -0
  372. package/dist/translations/es.js.map +1 -0
  373. package/dist/translations/fr.js +221 -0
  374. package/dist/translations/fr.js.map +1 -0
  375. package/dist/translations/id.js +221 -0
  376. package/dist/translations/id.js.map +1 -0
  377. package/dist/translations/index.d.ts +10 -1
  378. package/dist/translations/index.js +19 -1
  379. package/dist/translations/index.js.map +1 -1
  380. package/dist/translations/keys.d.ts +144 -0
  381. package/dist/translations/keys.js +145 -1
  382. package/dist/translations/keys.js.map +1 -1
  383. package/dist/translations/ko.js +221 -0
  384. package/dist/translations/ko.js.map +1 -0
  385. package/dist/translations/metricKeys.js +8 -2
  386. package/dist/translations/metricKeys.js.map +1 -1
  387. package/dist/translations/pt.js +221 -0
  388. package/dist/translations/pt.js.map +1 -0
  389. package/dist/translations/ru.js +221 -0
  390. package/dist/translations/ru.js.map +1 -0
  391. package/dist/translations/server.js.map +1 -1
  392. package/dist/translations/uk.js +221 -0
  393. package/dist/translations/uk.js.map +1 -0
  394. package/dist/translations/zh.js +221 -0
  395. package/dist/translations/zh.js.map +1 -0
  396. package/dist/view/AnalyticsNavLink.d.ts +19 -0
  397. package/dist/view/AnalyticsNavLink.js +40 -0
  398. package/dist/view/AnalyticsNavLink.js.map +1 -0
  399. package/dist/view/AnalyticsView.d.ts +23 -0
  400. package/dist/view/AnalyticsView.js +45 -0
  401. package/dist/view/AnalyticsView.js.map +1 -0
  402. package/dist/view/AnalyticsViewClient.d.ts +15 -0
  403. package/dist/view/AnalyticsViewClient.js +244 -0
  404. package/dist/view/AnalyticsViewClient.js.map +1 -0
  405. package/dist/view/authRedirect.js +32 -0
  406. package/dist/view/authRedirect.js.map +1 -0
  407. package/dist/view/conversionRate.js +18 -0
  408. package/dist/view/conversionRate.js.map +1 -0
  409. package/dist/view/dayRange.js +68 -0
  410. package/dist/view/dayRange.js.map +1 -0
  411. package/dist/view/gating.d.ts +1 -0
  412. package/dist/view/gating.js +142 -0
  413. package/dist/view/gating.js.map +1 -0
  414. package/dist/view/labels.js +76 -0
  415. package/dist/view/labels.js.map +1 -0
  416. package/dist/view/registerView.js +48 -0
  417. package/dist/view/registerView.js.map +1 -0
  418. package/dist/view/sections/Breakdowns.js +198 -0
  419. package/dist/view/sections/Breakdowns.js.map +1 -0
  420. package/dist/view/sections/EmptyStates.js +92 -0
  421. package/dist/view/sections/EmptyStates.js.map +1 -0
  422. package/dist/view/sections/FilterChips.js +46 -0
  423. package/dist/view/sections/FilterChips.js.map +1 -0
  424. package/dist/view/sections/GoalsPanel.js +82 -0
  425. package/dist/view/sections/GoalsPanel.js.map +1 -0
  426. package/dist/view/sections/OverviewCards.js +65 -0
  427. package/dist/view/sections/OverviewCards.js.map +1 -0
  428. package/dist/view/sections/RealtimeStrip.js +80 -0
  429. package/dist/view/sections/RealtimeStrip.js.map +1 -0
  430. package/dist/view/sections/Toolbar.js +207 -0
  431. package/dist/view/sections/Toolbar.js.map +1 -0
  432. package/dist/view/sections/Trend.js +125 -0
  433. package/dist/view/sections/Trend.js.map +1 -0
  434. package/dist/view/sections/styles.js +76 -0
  435. package/dist/view/sections/styles.js.map +1 -0
  436. package/dist/view/state.js +211 -0
  437. package/dist/view/state.js.map +1 -0
  438. package/dist/view/useViewQueries.js +153 -0
  439. package/dist/view/useViewQueries.js.map +1 -0
  440. package/dist/view/viewProps.d.ts +40 -0
  441. package/dist/view/viewProps.js +90 -0
  442. package/dist/view/viewProps.js.map +1 -0
  443. package/dist/widgets/AnalyticsBreakdownWidget.d.ts +2 -1
  444. package/dist/widgets/AnalyticsBreakdownWidget.js +78 -11
  445. package/dist/widgets/AnalyticsBreakdownWidget.js.map +1 -1
  446. package/dist/widgets/AnalyticsGoalsWidget.d.ts +14 -0
  447. package/dist/widgets/AnalyticsGoalsWidget.js +196 -0
  448. package/dist/widgets/AnalyticsGoalsWidget.js.map +1 -0
  449. package/dist/widgets/AnalyticsMetricWidget.d.ts +2 -1
  450. package/dist/widgets/AnalyticsMetricWidget.js +63 -13
  451. package/dist/widgets/AnalyticsMetricWidget.js.map +1 -1
  452. package/dist/widgets/AnalyticsRealtimeWidget.d.ts +2 -1
  453. package/dist/widgets/AnalyticsRealtimeWidget.js +44 -22
  454. package/dist/widgets/AnalyticsRealtimeWidget.js.map +1 -1
  455. package/dist/widgets/AnalyticsTrendWidget.d.ts +2 -1
  456. package/dist/widgets/AnalyticsTrendWidget.js +79 -16
  457. package/dist/widgets/AnalyticsTrendWidget.js.map +1 -1
  458. package/dist/widgets/RealtimeCounter.d.ts +4 -0
  459. package/dist/widgets/RealtimeCounter.js +18 -4
  460. package/dist/widgets/RealtimeCounter.js.map +1 -1
  461. package/dist/widgets/WidgetViewLink.js +17 -0
  462. package/dist/widgets/WidgetViewLink.js.map +1 -0
  463. package/dist/widgets/breakdownTypes.js +38 -0
  464. package/dist/widgets/breakdownTypes.js.map +1 -1
  465. package/dist/widgets/cardChrome.js +31 -7
  466. package/dist/widgets/cardChrome.js.map +1 -1
  467. package/dist/widgets/comparison.js +15 -1
  468. package/dist/widgets/comparison.js.map +1 -1
  469. package/dist/widgets/defaults.d.ts +6 -2
  470. package/dist/widgets/defaults.js +78 -23
  471. package/dist/widgets/defaults.js.map +1 -1
  472. package/dist/widgets/filterCaption.js +27 -0
  473. package/dist/widgets/filterCaption.js.map +1 -0
  474. package/dist/widgets/filterField.d.ts +19 -0
  475. package/dist/widgets/filterField.js +75 -0
  476. package/dist/widgets/filterField.js.map +1 -0
  477. package/dist/widgets/prepareWidgetRead.d.ts +7 -0
  478. package/dist/widgets/prepareWidgetRead.js +74 -0
  479. package/dist/widgets/prepareWidgetRead.js.map +1 -0
  480. package/dist/widgets/range.js +43 -12
  481. package/dist/widgets/range.js.map +1 -1
  482. package/dist/widgets/readForWidget.d.ts +26 -3
  483. package/dist/widgets/readForWidget.js +48 -44
  484. package/dist/widgets/readForWidget.js.map +1 -1
  485. package/dist/widgets/readForWidgetBreakdown.d.ts +34 -2
  486. package/dist/widgets/readForWidgetBreakdown.js +53 -49
  487. package/dist/widgets/readForWidgetBreakdown.js.map +1 -1
  488. package/dist/widgets/readForWidgetGoals.d.ts +67 -0
  489. package/dist/widgets/readForWidgetGoals.js +140 -0
  490. package/dist/widgets/readForWidgetGoals.js.map +1 -0
  491. package/dist/widgets/readForWidgetRealtime.d.ts +8 -0
  492. package/dist/widgets/readForWidgetRealtime.js +23 -21
  493. package/dist/widgets/readForWidgetRealtime.js.map +1 -1
  494. package/dist/widgets/readForWidgetSeries.d.ts +26 -2
  495. package/dist/widgets/readForWidgetSeries.js +78 -53
  496. package/dist/widgets/readForWidgetSeries.js.map +1 -1
  497. package/dist/widgets/readMeta.js +18 -0
  498. package/dist/widgets/readMeta.js.map +1 -0
  499. package/dist/widgets/realtimePoll.js +13 -1
  500. package/dist/widgets/realtimePoll.js.map +1 -1
  501. package/dist/widgets/registerWidgets.js +62 -10
  502. package/dist/widgets/registerWidgets.js.map +1 -1
  503. package/dist/widgets/types.d.ts +15 -0
  504. package/dist/widgets/types.js +16 -2
  505. package/dist/widgets/types.js.map +1 -1
  506. package/dist/widgets/viewLink.d.ts +22 -0
  507. package/dist/widgets/viewLink.js +86 -0
  508. package/dist/widgets/viewLink.js.map +1 -0
  509. package/package.json +28 -8
  510. package/dist/native/rollups/applyDistinctDeltas.js +0 -9
  511. package/dist/native/rollups/applyDistinctDeltas.js.map +0 -1
  512. package/dist/native/rollups/bumpRollup.js +0 -68
  513. package/dist/native/rollups/bumpRollup.js.map +0 -1
  514. package/dist/native/rollups/insertIfNew.js +0 -19
  515. package/dist/native/rollups/insertIfNew.js.map +0 -1
@@ -0,0 +1,140 @@
1
+ import { resolveGoalsDetailedFor } from "../plugin/runtime.js";
2
+ import { comparisonOf } from "../core/capabilities.js";
3
+ import { previousWindow, withinLookback } from "./comparison.js";
4
+ import { prepareWidgetRead } from "./prepareWidgetRead.js";
5
+ import { readForWidget } from "./readForWidget.js";
6
+ import { readForWidgetBreakdown } from "./readForWidgetBreakdown.js";
7
+ import { conversionRate } from "../view/conversionRate.js";
8
+ //#region src/widgets/readForWidgetGoals.ts
9
+ /**
10
+ * How much wider than the table the previous window is read. Both windows rank by their own
11
+ * conversions, so a goal in today's top rows may sit well below them in the previous window;
12
+ * reading only as many rows as the table shows would drop exactly those deltas. Capped at
13
+ * the bound every analytics query is held to.
14
+ */
15
+ const PREVIOUS_LIMIT_FACTOR = 4;
16
+ const previousLimit = (limit) => Math.min(limit * PREVIOUS_LIMIT_FACTOR, 500);
17
+ /**
18
+ * Goal names for the read's own scope. A resolver that throws must not cost the widget its
19
+ * table, so the rows fall back to their slugs; the failure travels on as the hint, which is
20
+ * what tells the read apart from a scope that configured no goals at all.
21
+ */
22
+ const goalNames = async (runtime, req, scope) => {
23
+ try {
24
+ const resolved = await resolveGoalsDetailedFor(runtime, req, scope);
25
+ return new Map(resolved.map(({ goal }) => [goal.slug, goal.name]));
26
+ } catch (err) {
27
+ req.payload.logger?.warn(`analytics: widget goal names failed to resolve: ${String(err)}`);
28
+ return "unresolved";
29
+ }
30
+ };
31
+ /**
32
+ * The goals table behind the goals widget: conversions per goal over the window, each with
33
+ * its revenue, its share of the site's visitors, and (when comparing) the same goal's
34
+ * conversions in the previous window. Rows come from one `goal` breakdown read and the site
35
+ * total from one totals read, both through the existing widget helpers so capability
36
+ * gating, scoping and caching stay in one place. Revenue and visitors ride along only where
37
+ * the source serves them; the status is the breakdown's, since a table without its rows has
38
+ * nothing to show.
39
+ */
40
+ const readForWidgetGoals = async (args) => {
41
+ const { req, timeframe, limit, compare, adapterId, now } = args;
42
+ const fallback = (status, id, window) => ({
43
+ status,
44
+ adapterId: id,
45
+ rows: [],
46
+ ...window
47
+ });
48
+ const prepared = await prepareWidgetRead({
49
+ req,
50
+ now,
51
+ timeframe,
52
+ adapterId,
53
+ scope: args.scope,
54
+ timezone: args.timezone,
55
+ range: args.range
56
+ });
57
+ if (!prepared.ok) return fallback(prepared.status, prepared.adapterId, {
58
+ dateRange: prepared.dateRange,
59
+ timezone: prepared.tz
60
+ });
61
+ const { runtime, adapter, tz, dateRange } = prepared;
62
+ const shared = {
63
+ req,
64
+ timeframe,
65
+ adapterId: adapter.id,
66
+ scope: prepared.scope,
67
+ timezone: tz,
68
+ now
69
+ };
70
+ const previousRange = compare && runtime.comparison && comparisonOf(adapter.capabilities) ? previousWindow(dateRange, tz) : null;
71
+ const comparisonRange = previousRange && withinLookback(previousRange, adapter.capabilities.maxLookbackDays, {
72
+ tz,
73
+ now
74
+ }) ? previousRange : void 0;
75
+ const resolved = await goalNames(runtime, req, prepared.scope);
76
+ const names = resolved === "unresolved" ? /* @__PURE__ */ new Map() : resolved;
77
+ const goalSlugs = resolved === "unresolved" ? "unresolved" : [...names.keys()];
78
+ const [breakdown, totals, previous] = await Promise.all([
79
+ readForWidgetBreakdown({
80
+ ...shared,
81
+ range: dateRange,
82
+ metric: "conversions",
83
+ dimension: "goal",
84
+ limit,
85
+ extraMetrics: ["revenue", "visitors"],
86
+ goalSlugs
87
+ }),
88
+ adapter.capabilities.metrics.has("visitors") ? readForWidget({
89
+ ...shared,
90
+ range: dateRange,
91
+ metrics: ["visitors"],
92
+ comparison: false
93
+ }) : void 0,
94
+ comparisonRange ? readForWidgetBreakdown({
95
+ ...shared,
96
+ range: comparisonRange,
97
+ metric: "conversions",
98
+ dimension: "goal",
99
+ limit: previousLimit(limit),
100
+ goalSlugs
101
+ }) : void 0
102
+ ]);
103
+ if (breakdown.status !== "ok") return fallback(breakdown.status, breakdown.adapterId, {
104
+ dateRange,
105
+ timezone: tz
106
+ });
107
+ const previousBySlug = new Map((previous?.status === "ok" ? previous.rows : []).map((row) => [row.label, row.value]));
108
+ const siteVisitors = totals?.status === "ok" ? totals.metrics.visitors : void 0;
109
+ const rows = breakdown.rows.map((row) => {
110
+ const rate = conversionRate(row.metrics?.visitors, siteVisitors);
111
+ const previousConversions = previousBySlug.get(row.label);
112
+ return {
113
+ slug: row.label,
114
+ name: names.get(row.label) ?? row.label,
115
+ conversions: row.value,
116
+ ...row.metrics?.revenue !== void 0 ? { revenue: row.metrics.revenue } : {},
117
+ ...rate !== null ? { rate } : {},
118
+ ...previousConversions !== void 0 ? { previousConversions } : {}
119
+ };
120
+ }).sort((a, b) => b.conversions - a.conversions).slice(0, limit);
121
+ return {
122
+ status: "ok",
123
+ adapterId: adapter.id,
124
+ dateRange,
125
+ timezone: tz,
126
+ rows,
127
+ ...siteVisitors !== void 0 ? { siteVisitors } : {},
128
+ ...breakdown.provider === void 0 ? {} : { provider: breakdown.provider },
129
+ clamped: Boolean(breakdown.clamped || totals?.clamped || previous?.clamped),
130
+ stale: Boolean(breakdown.stale || totals?.stale || previous?.stale),
131
+ filtersUnapplied: Boolean(breakdown.filtersUnapplied || totals?.filtersUnapplied || previous?.filtersUnapplied),
132
+ sampled: Boolean(breakdown.sampled || totals?.sampled || previous?.sampled),
133
+ goalsUnresolved: breakdown.goalsUnresolved === true,
134
+ noGoals: breakdown.noGoals === true
135
+ };
136
+ };
137
+ //#endregion
138
+ export { readForWidgetGoals };
139
+
140
+ //# sourceMappingURL=readForWidgetGoals.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"readForWidgetGoals.js","names":[],"sources":["../../src/widgets/readForWidgetGoals.ts"],"sourcesContent":["import type { PayloadRequest } from 'payload'\nimport { comparisonOf } from '../core/capabilities'\nimport type { DateRange } from '../core/contract'\nimport { type AnalyticsRuntime, resolveGoalsDetailedFor } from '../plugin/runtime'\nimport { MAX_QUERY_LIMIT } from '../query/limits'\nimport type { TimeframePreset } from '../timeframe/presets'\nimport { conversionRate } from '../view/conversionRate'\nimport { previousWindow, withinLookback } from './comparison'\nimport { prepareWidgetRead, type WidgetReadStatus } from './prepareWidgetRead'\nimport { readForWidget } from './readForWidget'\nimport { readForWidgetBreakdown } from './readForWidgetBreakdown'\n\nexport interface GoalRow {\n\tslug: string\n\t/** The goal's admin-facing name, or its slug when no configured goal claims it. */\n\tname: string\n\tconversions: number\n\trevenue?: number\n\t/** 0..1 share of the site's visitors, absent when either side of the ratio is missing. */\n\trate?: number\n\tpreviousConversions?: number\n}\n\nexport interface WidgetGoalsResult {\n\tstatus: WidgetReadStatus\n\tadapterId: string\n\tdateRange: DateRange\n\ttimezone: string\n\trows: GoalRow[]\n\t/** Range total the rate divides by; absent when the source does not serve visitors. */\n\tsiteVisitors?: number\n\t/** The source that answered, absent on a read that never reached one. */\n\tprovider?: string\n\tclamped?: boolean\n\tstale?: boolean\n\t/** True when the source answered without one of the filters a read carried. */\n\tfiltersUnapplied?: boolean\n\t/** True when a read hit the source's event scan cap, so the numbers are a floor. */\n\tsampled?: boolean\n\t/** True when the source could not read the scope's goals, so the empty table means nothing. */\n\tgoalsUnresolved?: boolean\n\t/** True when the scope configures no goals at all, which is an empty table, not a failure. */\n\tnoGoals?: boolean\n}\n\nexport interface ReadForWidgetGoalsArgs {\n\treq: PayloadRequest\n\ttimeframe: TimeframePreset\n\tlimit: number\n\t/** Read the previous window too, when the source can compare. */\n\tcompare: boolean\n\tadapterId?: string\n\tnow: Date\n\trange?: DateRange\n\t/** Explicit scope override; omitted resolves via the plugin's scopeResolver. */\n\tscope?: string | null\n\t/**\n\t * Reporting timezone the caller already resolved, reused rather than resolved again so\n\t * a caller-supplied `range` is read in the very timezone it was interpreted in.\n\t */\n\ttimezone?: string\n}\n\n/**\n * How much wider than the table the previous window is read. Both windows rank by their own\n * conversions, so a goal in today's top rows may sit well below them in the previous window;\n * reading only as many rows as the table shows would drop exactly those deltas. Capped at\n * the bound every analytics query is held to.\n */\nconst PREVIOUS_LIMIT_FACTOR = 4\n\nconst previousLimit = (limit: number): number =>\n\tMath.min(limit * PREVIOUS_LIMIT_FACTOR, MAX_QUERY_LIMIT)\n\n/**\n * Goal names for the read's own scope. A resolver that throws must not cost the widget its\n * table, so the rows fall back to their slugs; the failure travels on as the hint, which is\n * what tells the read apart from a scope that configured no goals at all.\n */\nconst goalNames = async (\n\truntime: AnalyticsRuntime,\n\treq: PayloadRequest,\n\tscope: string | null\n): Promise<Map<string, string> | 'unresolved'> => {\n\ttry {\n\t\tconst resolved = await resolveGoalsDetailedFor(runtime, req, scope)\n\t\treturn new Map(resolved.map(({ goal }) => [goal.slug, goal.name]))\n\t} catch (err) {\n\t\treq.payload.logger?.warn(`analytics: widget goal names failed to resolve: ${String(err)}`)\n\t\treturn 'unresolved'\n\t}\n}\n\n/**\n * The goals table behind the goals widget: conversions per goal over the window, each with\n * its revenue, its share of the site's visitors, and (when comparing) the same goal's\n * conversions in the previous window. Rows come from one `goal` breakdown read and the site\n * total from one totals read, both through the existing widget helpers so capability\n * gating, scoping and caching stay in one place. Revenue and visitors ride along only where\n * the source serves them; the status is the breakdown's, since a table without its rows has\n * nothing to show.\n */\nexport const readForWidgetGoals = async (\n\targs: ReadForWidgetGoalsArgs\n): Promise<WidgetGoalsResult> => {\n\tconst { req, timeframe, limit, compare, adapterId, now } = args\n\tconst fallback = (\n\t\tstatus: WidgetReadStatus,\n\t\tid: string,\n\t\twindow: { dateRange: DateRange; timezone: string }\n\t): WidgetGoalsResult => ({ status, adapterId: id, rows: [], ...window })\n\n\tconst prepared = await prepareWidgetRead({\n\t\treq,\n\t\tnow,\n\t\ttimeframe,\n\t\tadapterId,\n\t\tscope: args.scope,\n\t\ttimezone: args.timezone,\n\t\trange: args.range,\n\t})\n\tif (!prepared.ok) {\n\t\treturn fallback(prepared.status, prepared.adapterId, {\n\t\t\tdateRange: prepared.dateRange,\n\t\t\ttimezone: prepared.tz,\n\t\t})\n\t}\n\tconst { runtime, adapter, tz, dateRange } = prepared\n\t// The sub-reads resolve their own context; pinning the adapter, scope, timezone and\n\t// window keeps all three answering about exactly the same read.\n\tconst shared = { req, timeframe, adapterId: adapter.id, scope: prepared.scope, timezone: tz, now }\n\tconst previousRange =\n\t\tcompare && runtime.comparison && comparisonOf(adapter.capabilities)\n\t\t\t? previousWindow(dateRange, tz)\n\t\t\t: null\n\tconst comparisonRange =\n\t\tpreviousRange &&\n\t\twithinLookback(previousRange, adapter.capabilities.maxLookbackDays, { tz, now })\n\t\t\t? previousRange\n\t\t\t: undefined\n\n\t// The names are resolved first: their slugs are the hint a provider source restricts its\n\t// goal rows to, so both reads below need them before they run.\n\tconst resolved = await goalNames(runtime, req, prepared.scope)\n\tconst names = resolved === 'unresolved' ? new Map<string, string>() : resolved\n\tconst goalSlugs = resolved === 'unresolved' ? 'unresolved' : [...names.keys()]\n\tconst [breakdown, totals, previous] = await Promise.all([\n\t\treadForWidgetBreakdown({\n\t\t\t...shared,\n\t\t\trange: dateRange,\n\t\t\tmetric: 'conversions',\n\t\t\tdimension: 'goal',\n\t\t\tlimit,\n\t\t\textraMetrics: ['revenue', 'visitors'],\n\t\t\tgoalSlugs,\n\t\t}),\n\t\tadapter.capabilities.metrics.has('visitors')\n\t\t\t? // The site total is a denominator, never a delta: its own previous window would\n\t\t\t\t// be a second read nothing renders.\n\t\t\t\treadForWidget({ ...shared, range: dateRange, metrics: ['visitors'], comparison: false })\n\t\t\t: undefined,\n\t\tcomparisonRange\n\t\t\t? readForWidgetBreakdown({\n\t\t\t\t\t...shared,\n\t\t\t\t\trange: comparisonRange,\n\t\t\t\t\tmetric: 'conversions',\n\t\t\t\t\tdimension: 'goal',\n\t\t\t\t\tlimit: previousLimit(limit),\n\t\t\t\t\tgoalSlugs,\n\t\t\t\t})\n\t\t\t: undefined,\n\t])\n\tif (breakdown.status !== 'ok') {\n\t\treturn fallback(breakdown.status, breakdown.adapterId, { dateRange, timezone: tz })\n\t}\n\n\tconst previousBySlug = new Map(\n\t\t(previous?.status === 'ok' ? previous.rows : []).map((row) => [row.label, row.value])\n\t)\n\tconst siteVisitors = totals?.status === 'ok' ? totals.metrics.visitors : undefined\n\tconst rows: GoalRow[] = breakdown.rows\n\t\t.map((row) => {\n\t\t\tconst rate = conversionRate(row.metrics?.visitors, siteVisitors)\n\t\t\tconst previousConversions = previousBySlug.get(row.label)\n\t\t\treturn {\n\t\t\t\tslug: row.label,\n\t\t\t\tname: names.get(row.label) ?? row.label,\n\t\t\t\tconversions: row.value,\n\t\t\t\t...(row.metrics?.revenue !== undefined ? { revenue: row.metrics.revenue } : {}),\n\t\t\t\t...(rate !== null ? { rate } : {}),\n\t\t\t\t...(previousConversions !== undefined ? { previousConversions } : {}),\n\t\t\t}\n\t\t})\n\t\t// The adapter ranks and caps already; re-applying both keeps one that does not from\n\t\t// spilling a long, unranked table into a dashboard card.\n\t\t.sort((a, b) => b.conversions - a.conversions)\n\t\t.slice(0, limit)\n\n\treturn {\n\t\tstatus: 'ok',\n\t\tadapterId: adapter.id,\n\t\tdateRange,\n\t\ttimezone: tz,\n\t\trows,\n\t\t...(siteVisitors !== undefined ? { siteVisitors } : {}),\n\t\t...(breakdown.provider === undefined ? {} : { provider: breakdown.provider }),\n\t\tclamped: Boolean(breakdown.clamped || totals?.clamped || previous?.clamped),\n\t\tstale: Boolean(breakdown.stale || totals?.stale || previous?.stale),\n\t\tfiltersUnapplied: Boolean(\n\t\t\tbreakdown.filtersUnapplied || totals?.filtersUnapplied || previous?.filtersUnapplied\n\t\t),\n\t\tsampled: Boolean(breakdown.sampled || totals?.sampled || previous?.sampled),\n\t\tgoalsUnresolved: breakdown.goalsUnresolved === true,\n\t\tnoGoals: breakdown.noGoals === true,\n\t}\n}\n"],"mappings":"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"}
@@ -12,6 +12,14 @@ interface WidgetRealtimeResult {
12
12
  adapterId: string;
13
13
  activeNow: number;
14
14
  series: RealtimePoint[];
15
+ /** The source that answered, absent on a read that never reached one. */
16
+ provider?: string;
17
+ clamped?: boolean;
18
+ stale?: boolean;
19
+ filtersUnapplied?: boolean;
20
+ goalsUnresolved?: boolean;
21
+ /** True when the read hit the source's event scan cap, so the counts are a floor. */
22
+ sampled?: boolean;
15
23
  }
16
24
  interface ReadForWidgetRealtimeArgs {
17
25
  req: PayloadRequest;
@@ -1,6 +1,6 @@
1
- import { satisfiesCapabilities } from "../core/capabilities.js";
2
- import { getRuntime } from "../plugin/runtime.js";
3
- import { resolveReadContext } from "../core/scopedRead.js";
1
+ import { cacheEpochFor } from "../plugin/runtime.js";
2
+ import { prepareWidgetRead } from "./prepareWidgetRead.js";
3
+ import { readMeta } from "./readMeta.js";
4
4
  import { kvCacheStore } from "../surfacing/cacheStore.js";
5
5
  //#region src/widgets/readForWidgetRealtime.ts
6
6
  const empty = (status, adapterId) => ({
@@ -17,33 +17,34 @@ const empty = (status, adapterId) => ({
17
17
  */
18
18
  const readForWidgetRealtime = async (args) => {
19
19
  const { req, metric, windowMinutes, adapterId, now } = args;
20
- const runtime = getRuntime(req.payload);
21
- if (!runtime) return empty("unavailable", adapterId ?? "");
22
- const ctx = await resolveReadContext({
23
- runtime,
20
+ const dateRange = {
21
+ start: /* @__PURE__ */ new Date(now.getTime() - windowMinutes * 6e4),
22
+ end: now
23
+ };
24
+ const prepared = await prepareWidgetRead({
24
25
  req,
26
+ now,
27
+ range: dateRange,
28
+ timezone: "UTC",
25
29
  adapterId,
26
- scope: args.scope
30
+ scope: args.scope,
31
+ requires: { realtime: true }
27
32
  });
28
- if (!ctx.ok) return empty("unavailable", adapterId ?? "");
29
- const adapter = ctx.adapter;
30
- if (!adapter.isConfigured()) return empty("not-configured", adapter.id);
31
- if (!adapter.realtime || !satisfiesCapabilities(adapter.capabilities, { realtime: true })) return empty("unavailable", adapter.id);
33
+ if (!prepared.ok) return empty(prepared.status === "not-configured" ? "not-configured" : "unavailable", prepared.adapterId);
34
+ const { runtime, adapter, queryScope } = prepared;
35
+ const realtime = adapter.realtime;
36
+ if (!realtime) return empty("unavailable", adapter.id);
32
37
  const ttlSeconds = runtime.ttl.realtime ?? adapter.capabilities.recommendedTtl.realtime;
33
38
  const bucket = Math.floor(now.getTime() / 1e3 / Math.max(1, ttlSeconds));
34
- const scopeKey = ctx.queryScope === void 0 ? "" : `:${encodeURIComponent(ctx.queryScope)}`;
35
- const key = `rt:${adapter.id}:${metric}:${windowMinutes}:${bucket}${scopeKey}`;
39
+ const scopeKey = queryScope === void 0 ? "" : `:${encodeURIComponent(queryScope)}`;
40
+ const key = `rt:e${await cacheEpochFor(runtime, queryScope)}:${adapter.id}:${metric}:${windowMinutes}:${bucket}${scopeKey}`;
36
41
  const store = kvCacheStore(req.payload.kv);
37
42
  const cached = await store.get(key);
38
43
  if (cached) return cached;
39
- const dateRange = {
40
- start: /* @__PURE__ */ new Date(now.getTime() - windowMinutes * 6e4),
41
- end: now
42
- };
43
- const result = await adapter.realtime({
44
+ const result = await realtime({
44
45
  metrics: [metric],
45
46
  dateRange,
46
- scope: ctx.queryScope
47
+ scope: queryScope
47
48
  }, {});
48
49
  const out = {
49
50
  status: "ok",
@@ -52,7 +53,8 @@ const readForWidgetRealtime = async (args) => {
52
53
  series: result.rows.map((r) => ({
53
54
  date: r.timestamp ?? "",
54
55
  value: r.metrics[metric] ?? 0
55
- }))
56
+ })),
57
+ ...readMeta(result)
56
58
  };
57
59
  await store.set(key, out, ttlSeconds);
58
60
  return out;
@@ -1 +1 @@
1
- {"version":3,"file":"readForWidgetRealtime.js","names":[],"sources":["../../src/widgets/readForWidgetRealtime.ts"],"sourcesContent":["import type { PayloadRequest } from 'payload'\nimport { satisfiesCapabilities } from '../core/capabilities'\nimport type { AnalyticsAdapter, MetricKey } from '../core/contract'\nimport { resolveReadContext } from '../core/scopedRead'\nimport { getRuntime } from '../plugin/runtime'\nimport { kvCacheStore } from '../surfacing/cacheStore'\n\nexport type WidgetRealtimeStatus = 'ok' | 'not-configured' | 'unavailable'\n\nexport interface RealtimePoint {\n\tdate: string\n\tvalue: number\n}\n\nexport interface WidgetRealtimeResult {\n\tstatus: WidgetRealtimeStatus\n\tadapterId: string\n\tactiveNow: number\n\tseries: RealtimePoint[]\n}\n\nexport interface ReadForWidgetRealtimeArgs {\n\treq: PayloadRequest\n\tmetric: MetricKey\n\twindowMinutes: number\n\tadapterId?: string\n\tnow: Date\n\t/** Explicit scope override; omitted resolves via the plugin's scopeResolver. */\n\tscope?: string | null\n}\n\nconst empty = (status: WidgetRealtimeStatus, adapterId: string): WidgetRealtimeResult => ({\n\tstatus,\n\tadapterId,\n\tactiveNow: 0,\n\tseries: [],\n})\n\n/**\n * Site-wide realtime read for the \"active now\" widget. The window arrives as a\n * dateRange (now - windowMinutes -> now). Cached under a realtime-specific key bucketed\n * to the realtime TTL: it is deliberately NOT routed through the engine, whose key\n * day-snaps the range (so a \"last 30 min\" read would collide with a \"today\" aggregate).\n */\nexport const readForWidgetRealtime = async (\n\targs: ReadForWidgetRealtimeArgs\n): Promise<WidgetRealtimeResult> => {\n\tconst { req, metric, windowMinutes, adapterId, now } = args\n\tconst runtime = getRuntime(req.payload)\n\tif (!runtime) {\n\t\treturn empty('unavailable', adapterId ?? '')\n\t}\n\tconst ctx = await resolveReadContext({ runtime, req, adapterId, scope: args.scope })\n\tif (!ctx.ok) {\n\t\treturn empty('unavailable', adapterId ?? '')\n\t}\n\tconst adapter: AnalyticsAdapter = ctx.adapter\n\tif (!adapter.isConfigured()) {\n\t\treturn empty('not-configured', adapter.id)\n\t}\n\tif (!adapter.realtime || !satisfiesCapabilities(adapter.capabilities, { realtime: true })) {\n\t\treturn empty('unavailable', adapter.id)\n\t}\n\n\tconst ttlSeconds = runtime.ttl.realtime ?? adapter.capabilities.recommendedTtl.realtime\n\tconst bucket = Math.floor(now.getTime() / 1000 / Math.max(1, ttlSeconds))\n\tconst scopeKey = ctx.queryScope === undefined ? '' : `:${encodeURIComponent(ctx.queryScope)}`\n\tconst key = `rt:${adapter.id}:${metric}:${windowMinutes}:${bucket}${scopeKey}`\n\tconst store = kvCacheStore(req.payload.kv)\n\tconst cached = await store.get<WidgetRealtimeResult>(key)\n\tif (cached) {\n\t\treturn cached\n\t}\n\n\tconst dateRange = { start: new Date(now.getTime() - windowMinutes * 60_000), end: now }\n\tconst result = await adapter.realtime({ metrics: [metric], dateRange, scope: ctx.queryScope }, {})\n\tconst out: WidgetRealtimeResult = {\n\t\tstatus: 'ok',\n\t\tadapterId: adapter.id,\n\t\tactiveNow: result.totals?.[metric] ?? 0,\n\t\tseries: result.rows.map((r) => ({ date: r.timestamp ?? '', value: r.metrics[metric] ?? 0 })),\n\t}\n\tawait store.set(key, out, ttlSeconds)\n\treturn out\n}\n"],"mappings":";;;;;AA+BA,MAAM,SAAS,QAA8B,eAA6C;CACzF;CACA;CACA,WAAW;CACX,QAAQ,CAAC;AACV;;;;;;;AAQA,MAAa,wBAAwB,OACpC,SACmC;CACnC,MAAM,EAAE,KAAK,QAAQ,eAAe,WAAW,QAAQ;CACvD,MAAM,UAAU,WAAW,IAAI,OAAO;CACtC,IAAI,CAAC,SACJ,OAAO,MAAM,eAAe,aAAa,EAAE;CAE5C,MAAM,MAAM,MAAM,mBAAmB;EAAE;EAAS;EAAK;EAAW,OAAO,KAAK;CAAM,CAAC;CACnF,IAAI,CAAC,IAAI,IACR,OAAO,MAAM,eAAe,aAAa,EAAE;CAE5C,MAAM,UAA4B,IAAI;CACtC,IAAI,CAAC,QAAQ,aAAa,GACzB,OAAO,MAAM,kBAAkB,QAAQ,EAAE;CAE1C,IAAI,CAAC,QAAQ,YAAY,CAAC,sBAAsB,QAAQ,cAAc,EAAE,UAAU,KAAK,CAAC,GACvF,OAAO,MAAM,eAAe,QAAQ,EAAE;CAGvC,MAAM,aAAa,QAAQ,IAAI,YAAY,QAAQ,aAAa,eAAe;CAC/E,MAAM,SAAS,KAAK,MAAM,IAAI,QAAQ,IAAI,MAAO,KAAK,IAAI,GAAG,UAAU,CAAC;CACxE,MAAM,WAAW,IAAI,eAAe,KAAA,IAAY,KAAK,IAAI,mBAAmB,IAAI,UAAU;CAC1F,MAAM,MAAM,MAAM,QAAQ,GAAG,GAAG,OAAO,GAAG,cAAc,GAAG,SAAS;CACpE,MAAM,QAAQ,aAAa,IAAI,QAAQ,EAAE;CACzC,MAAM,SAAS,MAAM,MAAM,IAA0B,GAAG;CACxD,IAAI,QACH,OAAO;CAGR,MAAM,YAAY;EAAE,uBAAO,IAAI,KAAK,IAAI,QAAQ,IAAI,gBAAgB,GAAM;EAAG,KAAK;CAAI;CACtF,MAAM,SAAS,MAAM,QAAQ,SAAS;EAAE,SAAS,CAAC,MAAM;EAAG;EAAW,OAAO,IAAI;CAAW,GAAG,CAAC,CAAC;CACjG,MAAM,MAA4B;EACjC,QAAQ;EACR,WAAW,QAAQ;EACnB,WAAW,OAAO,SAAS,WAAW;EACtC,QAAQ,OAAO,KAAK,KAAK,OAAO;GAAE,MAAM,EAAE,aAAa;GAAI,OAAO,EAAE,QAAQ,WAAW;EAAE,EAAE;CAC5F;CACA,MAAM,MAAM,IAAI,KAAK,KAAK,UAAU;CACpC,OAAO;AACR"}
1
+ {"version":3,"file":"readForWidgetRealtime.js","names":[],"sources":["../../src/widgets/readForWidgetRealtime.ts"],"sourcesContent":["import type { PayloadRequest } from 'payload'\nimport type { MetricKey } from '../core/contract'\nimport { cacheEpochFor } from '../plugin/runtime'\nimport { kvCacheStore } from '../surfacing/cacheStore'\nimport { DEFAULT_TIMEZONE } from '../timeframe/tz'\nimport { prepareWidgetRead } from './prepareWidgetRead'\nimport { readMeta } from './readMeta'\n\nexport type WidgetRealtimeStatus = 'ok' | 'not-configured' | 'unavailable'\n\nexport interface RealtimePoint {\n\tdate: string\n\tvalue: number\n}\n\nexport interface WidgetRealtimeResult {\n\tstatus: WidgetRealtimeStatus\n\tadapterId: string\n\tactiveNow: number\n\tseries: RealtimePoint[]\n\t/** The source that answered, absent on a read that never reached one. */\n\tprovider?: string\n\tclamped?: boolean\n\tstale?: boolean\n\tfiltersUnapplied?: boolean\n\tgoalsUnresolved?: boolean\n\t/** True when the read hit the source's event scan cap, so the counts are a floor. */\n\tsampled?: boolean\n}\n\nexport interface ReadForWidgetRealtimeArgs {\n\treq: PayloadRequest\n\tmetric: MetricKey\n\twindowMinutes: number\n\tadapterId?: string\n\tnow: Date\n\t/** Explicit scope override; omitted resolves via the plugin's scopeResolver. */\n\tscope?: string | null\n}\n\nconst empty = (status: WidgetRealtimeStatus, adapterId: string): WidgetRealtimeResult => ({\n\tstatus,\n\tadapterId,\n\tactiveNow: 0,\n\tseries: [],\n})\n\n/**\n * Site-wide realtime read for the \"active now\" widget. The window arrives as a\n * dateRange (now - windowMinutes -> now). Cached under a realtime-specific key bucketed\n * to the realtime TTL: it is deliberately NOT routed through the engine, whose key\n * day-snaps the range (so a \"last 30 min\" read would collide with a \"today\" aggregate).\n */\nexport const readForWidgetRealtime = async (\n\targs: ReadForWidgetRealtimeArgs\n): Promise<WidgetRealtimeResult> => {\n\tconst { req, metric, windowMinutes, adapterId, now } = args\n\tconst dateRange = { start: new Date(now.getTime() - windowMinutes * 60_000), end: now }\n\t// The window is anchored on `now` and never rendered in a zone, so the poll skips the\n\t// install's timezone resolver rather than paying for it ahead of the cache check.\n\tconst prepared = await prepareWidgetRead({\n\t\treq,\n\t\tnow,\n\t\trange: dateRange,\n\t\ttimezone: DEFAULT_TIMEZONE,\n\t\tadapterId,\n\t\tscope: args.scope,\n\t\trequires: { realtime: true },\n\t})\n\tif (!prepared.ok) {\n\t\t// The window carries no filters, so `filter-unsupported` cannot arise here.\n\t\tconst status = prepared.status === 'not-configured' ? 'not-configured' : 'unavailable'\n\t\treturn empty(status, prepared.adapterId)\n\t}\n\tconst { runtime, adapter, queryScope } = prepared\n\t// The capability says the source counts live visitors; the hook is what reads them.\n\tconst realtime = adapter.realtime\n\tif (!realtime) {\n\t\treturn empty('unavailable', adapter.id)\n\t}\n\n\tconst ttlSeconds = runtime.ttl.realtime ?? adapter.capabilities.recommendedTtl.realtime\n\tconst bucket = Math.floor(now.getTime() / 1000 / Math.max(1, ttlSeconds))\n\tconst scopeKey = queryScope === undefined ? '' : `:${encodeURIComponent(queryScope)}`\n\t// This key is built outside the engine, so it carries the scope's epoch itself.\n\tconst epoch = await cacheEpochFor(runtime, queryScope)\n\tconst key = `rt:e${epoch}:${adapter.id}:${metric}:${windowMinutes}:${bucket}${scopeKey}`\n\tconst store = kvCacheStore(req.payload.kv)\n\tconst cached = await store.get<WidgetRealtimeResult>(key)\n\tif (cached) {\n\t\treturn cached\n\t}\n\n\tconst result = await realtime({ metrics: [metric], dateRange, scope: queryScope }, {})\n\tconst out: WidgetRealtimeResult = {\n\t\tstatus: 'ok',\n\t\tadapterId: adapter.id,\n\t\tactiveNow: result.totals?.[metric] ?? 0,\n\t\tseries: result.rows.map((r) => ({ date: r.timestamp ?? '', value: r.metrics[metric] ?? 0 })),\n\t\t...readMeta(result),\n\t}\n\tawait store.set(key, out, ttlSeconds)\n\treturn out\n}\n"],"mappings":";;;;;AAwCA,MAAM,SAAS,QAA8B,eAA6C;CACzF;CACA;CACA,WAAW;CACX,QAAQ,CAAC;AACV;;;;;;;AAQA,MAAa,wBAAwB,OACpC,SACmC;CACnC,MAAM,EAAE,KAAK,QAAQ,eAAe,WAAW,QAAQ;CACvD,MAAM,YAAY;EAAE,uBAAO,IAAI,KAAK,IAAI,QAAQ,IAAI,gBAAgB,GAAM;EAAG,KAAK;CAAI;CAGtF,MAAM,WAAW,MAAM,kBAAkB;EACxC;EACA;EACA,OAAO;EACP,UAAA;EACA;EACA,OAAO,KAAK;EACZ,UAAU,EAAE,UAAU,KAAK;CAC5B,CAAC;CACD,IAAI,CAAC,SAAS,IAGb,OAAO,MADQ,SAAS,WAAW,mBAAmB,mBAAmB,eACpD,SAAS,SAAS;CAExC,MAAM,EAAE,SAAS,SAAS,eAAe;CAEzC,MAAM,WAAW,QAAQ;CACzB,IAAI,CAAC,UACJ,OAAO,MAAM,eAAe,QAAQ,EAAE;CAGvC,MAAM,aAAa,QAAQ,IAAI,YAAY,QAAQ,aAAa,eAAe;CAC/E,MAAM,SAAS,KAAK,MAAM,IAAI,QAAQ,IAAI,MAAO,KAAK,IAAI,GAAG,UAAU,CAAC;CACxE,MAAM,WAAW,eAAe,KAAA,IAAY,KAAK,IAAI,mBAAmB,UAAU;CAGlF,MAAM,MAAM,OAAO,MADC,cAAc,SAAS,UAAU,EAC5B,GAAG,QAAQ,GAAG,GAAG,OAAO,GAAG,cAAc,GAAG,SAAS;CAC9E,MAAM,QAAQ,aAAa,IAAI,QAAQ,EAAE;CACzC,MAAM,SAAS,MAAM,MAAM,IAA0B,GAAG;CACxD,IAAI,QACH,OAAO;CAGR,MAAM,SAAS,MAAM,SAAS;EAAE,SAAS,CAAC,MAAM;EAAG;EAAW,OAAO;CAAW,GAAG,CAAC,CAAC;CACrF,MAAM,MAA4B;EACjC,QAAQ;EACR,WAAW,QAAQ;EACnB,WAAW,OAAO,SAAS,WAAW;EACtC,QAAQ,OAAO,KAAK,KAAK,OAAO;GAAE,MAAM,EAAE,aAAa;GAAI,OAAO,EAAE,QAAQ,WAAW;EAAE,EAAE;EAC3F,GAAG,SAAS,MAAM;CACnB;CACA,MAAM,MAAM,IAAI,KAAK,KAAK,UAAU;CACpC,OAAO;AACR"}
@@ -1,6 +1,6 @@
1
- import { DateRange, MetricKey } from "../core/contract.js";
1
+ import { AnalyticsFilter, DateRange, MetricKey } from "../core/contract.js";
2
2
  import { TimeframePreset } from "../timeframe/presets.js";
3
- import { WidgetReadStatus } from "./readForWidget.js";
3
+ import { WidgetReadStatus } from "./prepareWidgetRead.js";
4
4
  import { PayloadRequest } from "payload";
5
5
 
6
6
  //#region src/widgets/readForWidgetSeries.d.ts
@@ -16,11 +16,27 @@ interface WidgetSeriesResult {
16
16
  timezone: string;
17
17
  points: SeriesPoint[];
18
18
  total: number;
19
+ /** The source that answered, absent on a read that never reached one. */
20
+ provider?: string;
19
21
  clamped?: boolean;
22
+ /** True when the engine served a stale cache entry after a failed provider read. */
23
+ stale?: boolean;
24
+ /** True when the source answered without one of the filters the read carried. */
25
+ filtersUnapplied?: boolean;
26
+ /** True when the read hit the source's event scan cap, so the numbers are a floor. */
27
+ sampled?: boolean;
28
+ /** True when the source could not read the scope's goals, so a conversions series means nothing. */
29
+ goalsUnresolved?: boolean;
20
30
  /** Previous-window headline total, present only when the adapter supports comparison. */
21
31
  previousTotal?: number;
22
32
  /** The previous comparable window, present only when comparison ran. */
23
33
  comparisonRange?: DateRange;
34
+ /**
35
+ * The previous window's daily series, present only when `compare` was asked for and the
36
+ * adapter supports comparison. Zero-filled to the same length as `points`, so the
37
+ * previous window's day i overlays `points[i]`.
38
+ */
39
+ comparisonPoints?: SeriesPoint[];
24
40
  }
25
41
  interface ReadForWidgetSeriesArgs {
26
42
  req: PayloadRequest;
@@ -31,6 +47,14 @@ interface ReadForWidgetSeriesArgs {
31
47
  range?: DateRange;
32
48
  /** Explicit scope override; omitted resolves via the plugin's scopeResolver. */
33
49
  scope?: string | null;
50
+ /**
51
+ * Reporting timezone the caller already resolved, reused rather than resolved again so
52
+ * a caller-supplied `range` is read in the very timezone it was interpreted in.
53
+ */
54
+ timezone?: string;
55
+ filters?: AnalyticsFilter[];
56
+ /** Also return the previous window's series, for the chart's comparison overlay. */
57
+ compare?: boolean;
34
58
  }
35
59
  /**
36
60
  * Site-wide time-series read for a trend widget: resolve the timeframe, pick the
@@ -1,10 +1,8 @@
1
- import { satisfiesCapabilities } from "../core/capabilities.js";
2
- import { supportsGranularity } from "../core/granularity.js";
3
1
  import { addDaysInTz, startOfDayInTz, zonedDayIso } from "../timeframe/tz.js";
4
- import { getRuntime, resolveTimezoneFor } from "../plugin/runtime.js";
5
- import { resolveReadContext } from "../core/scopedRead.js";
6
- import { resolveTimeframe } from "../timeframe/presets.js";
7
- import { previousWindow } from "./comparison.js";
2
+ import { comparisonOf } from "../core/capabilities.js";
3
+ import { previousWindow, withinLookback } from "./comparison.js";
4
+ import { prepareWidgetRead } from "./prepareWidgetRead.js";
5
+ import { readMeta } from "./readMeta.js";
8
6
  //#region src/widgets/readForWidgetSeries.ts
9
7
  const MAX_SERIES_DAYS = 366;
10
8
  /**
@@ -37,78 +35,105 @@ const fillDailySeries = (args) => {
37
35
  }));
38
36
  };
39
37
  /**
38
+ * Project a comparison series onto the primary axis: day i of the previous window overlays
39
+ * day i of the current one. Both windows span the same day count by construction, so this
40
+ * only guards a DST-shifted or clamped edge, silently truncating or zero-filling; a filled
41
+ * bucket borrows the axis day so every point still carries a real date.
42
+ */
43
+ const alignSeries = (points, axis) => points.length === axis.length ? points : axis.map((day, i) => points[i] ?? {
44
+ date: day.date,
45
+ value: 0
46
+ });
47
+ /**
40
48
  * Site-wide time-series read for a trend widget: resolve the timeframe, pick the
41
49
  * adapter, gate on the metric and day-granularity support, read through the engine,
42
50
  * then return a zero-filled daily series plus the headline total. Mirrors
43
51
  * `readForWidget` but yields points instead of a single value.
44
52
  */
45
53
  const readForWidgetSeries = async (args) => {
46
- const { req, metric, timeframe, adapterId, now, range } = args;
47
- const fallback = (status, id) => ({
48
- status,
49
- adapterId: id,
50
- dateRange: range ?? resolveTimeframe(timeframe, now),
51
- timezone: "UTC",
52
- points: [],
53
- total: 0
54
- });
55
- const runtime = getRuntime(req.payload);
56
- if (!runtime) return fallback("unavailable", adapterId ?? "");
57
- const ctx = await resolveReadContext({
58
- runtime,
54
+ const { req, metric, timeframe, adapterId, now, range, filters, compare } = args;
55
+ const prepared = await prepareWidgetRead({
59
56
  req,
57
+ now,
58
+ timeframe,
60
59
  adapterId,
61
- scope: args.scope
60
+ scope: args.scope,
61
+ timezone: args.timezone,
62
+ range,
63
+ filters,
64
+ requires: { metrics: [metric] },
65
+ granularity: "day",
66
+ goalRead: () => ({ metrics: [metric] })
62
67
  });
63
- if (!ctx.ok) return fallback("unavailable", adapterId ?? "");
64
- const tz = await resolveTimezoneFor(runtime, req, ctx.scope);
65
- const dateRange = range ?? resolveTimeframe(timeframe, now, tz);
68
+ if (!prepared.ok) return {
69
+ status: prepared.status,
70
+ adapterId: prepared.adapterId,
71
+ dateRange: prepared.dateRange,
72
+ timezone: prepared.tz,
73
+ points: [],
74
+ total: 0
75
+ };
76
+ const { runtime, adapter, tz, dateRange, goalSlugs } = prepared;
66
77
  const base = {
67
78
  dateRange,
68
79
  timezone: tz,
69
80
  points: [],
70
81
  total: 0
71
82
  };
72
- const adapter = ctx.adapter;
73
- if (!adapter.isConfigured()) return {
74
- status: "not-configured",
75
- adapterId: adapter.id,
76
- ...base
77
- };
78
- if (!satisfiesCapabilities(adapter.capabilities, { metrics: [metric] }) || !supportsGranularity(adapter.capabilities, "day")) return {
79
- status: "unavailable",
80
- adapterId: adapter.id,
81
- ...base
82
- };
83
- const comparisonRange = runtime.comparison && adapter.capabilities.comparison ? previousWindow(dateRange, tz) ?? void 0 : void 0;
84
- const [result, previous] = await Promise.all([runtime.engine.read(adapter, {
83
+ const previousRange = runtime.comparison && comparisonOf(adapter.capabilities) ? previousWindow(dateRange, tz) : null;
84
+ const comparisonRange = previousRange && withinLookback(previousRange, adapter.capabilities.maxLookbackDays, {
85
+ tz,
86
+ now
87
+ }) ? previousRange : void 0;
88
+ const readBase = {
85
89
  metrics: [metric],
86
- dateRange,
87
- granularity: "day",
88
- timezone: tz,
89
- scope: ctx.queryScope
90
- }), comparisonRange ? runtime.engine.read(adapter, {
91
- metrics: [metric],
92
- dateRange: comparisonRange,
90
+ filters,
93
91
  timezone: tz,
94
- scope: ctx.queryScope
95
- }) : void 0]);
92
+ scope: prepared.queryScope,
93
+ ...goalSlugs === void 0 ? {} : { goalSlugs }
94
+ };
95
+ let result;
96
+ let previous;
97
+ try {
98
+ [result, previous] = await Promise.all([runtime.engine.read(adapter, {
99
+ ...readBase,
100
+ dateRange,
101
+ granularity: "day"
102
+ }), comparisonRange ? runtime.engine.read(adapter, {
103
+ ...readBase,
104
+ dateRange: comparisonRange,
105
+ ...compare ? { granularity: "day" } : {}
106
+ }) : void 0]);
107
+ } catch {
108
+ return {
109
+ status: "unavailable",
110
+ adapterId: adapter.id,
111
+ ...base
112
+ };
113
+ }
96
114
  const previousTotal = previous ? previous.totals?.[metric] : void 0;
115
+ const points = fillDailySeries({
116
+ rows: result.rows,
117
+ dateRange,
118
+ metric,
119
+ tz
120
+ });
97
121
  return {
98
122
  status: "ok",
99
123
  adapterId: adapter.id,
100
124
  dateRange,
101
125
  timezone: tz,
102
- points: fillDailySeries({
103
- rows: result.rows,
104
- dateRange,
105
- metric,
106
- tz
107
- }),
126
+ points,
108
127
  total: result.totals?.[metric] ?? 0,
109
- clamped: result.meta.clamped ?? false,
128
+ ...readMeta(result),
110
129
  previousTotal,
111
- comparisonRange
130
+ comparisonRange,
131
+ ...compare && previous && comparisonRange ? { comparisonPoints: alignSeries(fillDailySeries({
132
+ rows: previous.rows,
133
+ dateRange: comparisonRange,
134
+ metric,
135
+ tz
136
+ }), points) } : {}
112
137
  };
113
138
  };
114
139
  //#endregion
@@ -1 +1 @@
1
- {"version":3,"file":"readForWidgetSeries.js","names":[],"sources":["../../src/widgets/readForWidgetSeries.ts"],"sourcesContent":["import type { PayloadRequest } from 'payload'\nimport { satisfiesCapabilities } from '../core/capabilities'\nimport type { AnalyticsAdapter, AnalyticsRow, DateRange, MetricKey } from '../core/contract'\nimport { supportsGranularity } from '../core/granularity'\nimport { resolveReadContext } from '../core/scopedRead'\nimport { getRuntime, resolveTimezoneFor } from '../plugin/runtime'\nimport { resolveTimeframe, type TimeframePreset } from '../timeframe/presets'\nimport { addDaysInTz, DEFAULT_TIMEZONE, startOfDayInTz, zonedDayIso } from '../timeframe/tz'\nimport { previousWindow } from './comparison'\nimport type { WidgetReadStatus } from './readForWidget'\n\nexport interface SeriesPoint {\n\tdate: string\n\tvalue: number\n}\n\nexport interface WidgetSeriesResult {\n\tstatus: WidgetReadStatus\n\tadapterId: string\n\tdateRange: DateRange\n\t/** Reporting timezone the read resolved in; the trend axis buckets in it. */\n\ttimezone: string\n\tpoints: SeriesPoint[]\n\ttotal: number\n\tclamped?: boolean\n\t/** Previous-window headline total, present only when the adapter supports comparison. */\n\tpreviousTotal?: number\n\t/** The previous comparable window, present only when comparison ran. */\n\tcomparisonRange?: DateRange\n}\n\nexport interface ReadForWidgetSeriesArgs {\n\treq: PayloadRequest\n\tmetric: MetricKey\n\ttimeframe: TimeframePreset\n\tadapterId?: string\n\tnow: Date\n\trange?: DateRange\n\t/** Explicit scope override; omitted resolves via the plugin's scopeResolver. */\n\tscope?: string | null\n}\n\nconst MAX_SERIES_DAYS = 366\n\n/**\n * Project time-series rows onto a contiguous daily axis, zero-filling gaps. Days are\n * counted in `tz` (defaulting to UTC), so a reporting-timezone read aligns each bucket\n * to that zone's midnight. The axis is capped at the most recent `MAX_SERIES_DAYS` so\n * an unbounded range (all time) stays a bounded, drawable sparkline; the headline total\n * still reflects the full range.\n */\nexport const fillDailySeries = (args: {\n\trows: AnalyticsRow[]\n\tdateRange: DateRange\n\tmetric: MetricKey\n\ttz?: string\n}): SeriesPoint[] => {\n\tconst { rows, dateRange, metric } = args\n\tconst tz = args.tz ?? DEFAULT_TIMEZONE\n\tconst lastDay = startOfDayInTz(dateRange.end, tz)\n\tconst requestedStart = startOfDayInTz(dateRange.start, tz)\n\tconst byDay = new Map<string, number>()\n\tfor (const row of rows) {\n\t\tif (!row.timestamp) {\n\t\t\tcontinue\n\t\t}\n\t\tconst day = zonedDayIso(new Date(row.timestamp), tz)\n\t\tbyDay.set(day, (byDay.get(day) ?? 0) + (row.metrics[metric] ?? 0))\n\t}\n\t// Walk calendar days back from the last day so DST-length days never mis-step, capping\n\t// the axis at MAX_SERIES_DAYS or the requested start, whichever is more recent.\n\tconst isoDays: string[] = []\n\tlet cursor = lastDay\n\tfor (let i = 0; i < MAX_SERIES_DAYS && cursor.getTime() >= requestedStart.getTime(); i += 1) {\n\t\tisoDays.push(cursor.toISOString())\n\t\tcursor = addDaysInTz(cursor, -1, tz)\n\t}\n\treturn isoDays.reverse().map((date) => ({ date, value: byDay.get(date) ?? 0 }))\n}\n\n/**\n * Site-wide time-series read for a trend widget: resolve the timeframe, pick the\n * adapter, gate on the metric and day-granularity support, read through the engine,\n * then return a zero-filled daily series plus the headline total. Mirrors\n * `readForWidget` but yields points instead of a single value.\n */\nexport const readForWidgetSeries = async (\n\targs: ReadForWidgetSeriesArgs\n): Promise<WidgetSeriesResult> => {\n\tconst { req, metric, timeframe, adapterId, now, range } = args\n\tconst fallback = (status: WidgetReadStatus, id: string): WidgetSeriesResult => ({\n\t\tstatus,\n\t\tadapterId: id,\n\t\tdateRange: range ?? resolveTimeframe(timeframe, now),\n\t\ttimezone: DEFAULT_TIMEZONE,\n\t\tpoints: [],\n\t\ttotal: 0,\n\t})\n\n\tconst runtime = getRuntime(req.payload)\n\tif (!runtime) {\n\t\treturn fallback('unavailable', adapterId ?? '')\n\t}\n\tconst ctx = await resolveReadContext({ runtime, req, adapterId, scope: args.scope })\n\tif (!ctx.ok) {\n\t\treturn fallback('unavailable', adapterId ?? '')\n\t}\n\tconst tz = await resolveTimezoneFor(runtime, req, ctx.scope)\n\tconst dateRange = range ?? resolveTimeframe(timeframe, now, tz)\n\tconst base = { dateRange, timezone: tz, points: [] as SeriesPoint[], total: 0 }\n\tconst adapter: AnalyticsAdapter = ctx.adapter\n\tif (!adapter.isConfigured()) {\n\t\treturn { status: 'not-configured', adapterId: adapter.id, ...base }\n\t}\n\tif (\n\t\t!satisfiesCapabilities(adapter.capabilities, { metrics: [metric] }) ||\n\t\t!supportsGranularity(adapter.capabilities, 'day')\n\t) {\n\t\treturn { status: 'unavailable', adapterId: adapter.id, ...base }\n\t}\n\tconst comparisonRange =\n\t\truntime.comparison && adapter.capabilities.comparison\n\t\t\t? (previousWindow(dateRange, tz) ?? undefined)\n\t\t\t: undefined\n\tconst [result, previous] = await Promise.all([\n\t\truntime.engine.read(adapter, {\n\t\t\tmetrics: [metric],\n\t\t\tdateRange,\n\t\t\tgranularity: 'day',\n\t\t\ttimezone: tz,\n\t\t\tscope: ctx.queryScope,\n\t\t}),\n\t\tcomparisonRange\n\t\t\t? runtime.engine.read(adapter, {\n\t\t\t\t\tmetrics: [metric],\n\t\t\t\t\tdateRange: comparisonRange,\n\t\t\t\t\ttimezone: tz,\n\t\t\t\t\tscope: ctx.queryScope,\n\t\t\t\t})\n\t\t\t: undefined,\n\t])\n\tconst previousTotal = previous ? previous.totals?.[metric] : undefined\n\treturn {\n\t\tstatus: 'ok',\n\t\tadapterId: adapter.id,\n\t\tdateRange,\n\t\ttimezone: tz,\n\t\tpoints: fillDailySeries({ rows: result.rows, dateRange, metric, tz }),\n\t\ttotal: result.totals?.[metric] ?? 0,\n\t\tclamped: result.meta.clamped ?? false,\n\t\tpreviousTotal,\n\t\tcomparisonRange,\n\t}\n}\n"],"mappings":"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"}
1
+ {"version":3,"file":"readForWidgetSeries.js","names":[],"sources":["../../src/widgets/readForWidgetSeries.ts"],"sourcesContent":["import type { PayloadRequest } from 'payload'\nimport { comparisonOf } from '../core/capabilities'\nimport type {\n\tAnalyticsFilter,\n\tAnalyticsResult,\n\tAnalyticsRow,\n\tDateRange,\n\tMetricKey,\n} from '../core/contract'\nimport type { TimeframePreset } from '../timeframe/presets'\nimport { addDaysInTz, DEFAULT_TIMEZONE, startOfDayInTz, zonedDayIso } from '../timeframe/tz'\nimport { previousWindow, withinLookback } from './comparison'\nimport { prepareWidgetRead, type WidgetReadStatus } from './prepareWidgetRead'\nimport { readMeta } from './readMeta'\n\nexport interface SeriesPoint {\n\tdate: string\n\tvalue: number\n}\n\nexport interface WidgetSeriesResult {\n\tstatus: WidgetReadStatus\n\tadapterId: string\n\tdateRange: DateRange\n\t/** Reporting timezone the read resolved in; the trend axis buckets in it. */\n\ttimezone: string\n\tpoints: SeriesPoint[]\n\ttotal: number\n\t/** The source that answered, absent on a read that never reached one. */\n\tprovider?: string\n\tclamped?: boolean\n\t/** True when the engine served a stale cache entry after a failed provider read. */\n\tstale?: boolean\n\t/** True when the source answered without one of the filters the read carried. */\n\tfiltersUnapplied?: boolean\n\t/** True when the read hit the source's event scan cap, so the numbers are a floor. */\n\tsampled?: boolean\n\t/** True when the source could not read the scope's goals, so a conversions series means nothing. */\n\tgoalsUnresolved?: boolean\n\t/** Previous-window headline total, present only when the adapter supports comparison. */\n\tpreviousTotal?: number\n\t/** The previous comparable window, present only when comparison ran. */\n\tcomparisonRange?: DateRange\n\t/**\n\t * The previous window's daily series, present only when `compare` was asked for and the\n\t * adapter supports comparison. Zero-filled to the same length as `points`, so the\n\t * previous window's day i overlays `points[i]`.\n\t */\n\tcomparisonPoints?: SeriesPoint[]\n}\n\nexport interface ReadForWidgetSeriesArgs {\n\treq: PayloadRequest\n\tmetric: MetricKey\n\ttimeframe: TimeframePreset\n\tadapterId?: string\n\tnow: Date\n\trange?: DateRange\n\t/** Explicit scope override; omitted resolves via the plugin's scopeResolver. */\n\tscope?: string | null\n\t/**\n\t * Reporting timezone the caller already resolved, reused rather than resolved again so\n\t * a caller-supplied `range` is read in the very timezone it was interpreted in.\n\t */\n\ttimezone?: string\n\tfilters?: AnalyticsFilter[]\n\t/** Also return the previous window's series, for the chart's comparison overlay. */\n\tcompare?: boolean\n}\n\nconst MAX_SERIES_DAYS = 366\n\n/**\n * Project time-series rows onto a contiguous daily axis, zero-filling gaps. Days are\n * counted in `tz` (defaulting to UTC), so a reporting-timezone read aligns each bucket\n * to that zone's midnight. The axis is capped at the most recent `MAX_SERIES_DAYS` so\n * an unbounded range (all time) stays a bounded, drawable sparkline; the headline total\n * still reflects the full range.\n */\nexport const fillDailySeries = (args: {\n\trows: AnalyticsRow[]\n\tdateRange: DateRange\n\tmetric: MetricKey\n\ttz?: string\n}): SeriesPoint[] => {\n\tconst { rows, dateRange, metric } = args\n\tconst tz = args.tz ?? DEFAULT_TIMEZONE\n\tconst lastDay = startOfDayInTz(dateRange.end, tz)\n\tconst requestedStart = startOfDayInTz(dateRange.start, tz)\n\tconst byDay = new Map<string, number>()\n\tfor (const row of rows) {\n\t\tif (!row.timestamp) {\n\t\t\tcontinue\n\t\t}\n\t\tconst day = zonedDayIso(new Date(row.timestamp), tz)\n\t\tbyDay.set(day, (byDay.get(day) ?? 0) + (row.metrics[metric] ?? 0))\n\t}\n\t// Walk calendar days back from the last day so DST-length days never mis-step, capping\n\t// the axis at MAX_SERIES_DAYS or the requested start, whichever is more recent.\n\tconst isoDays: string[] = []\n\tlet cursor = lastDay\n\tfor (let i = 0; i < MAX_SERIES_DAYS && cursor.getTime() >= requestedStart.getTime(); i += 1) {\n\t\tisoDays.push(cursor.toISOString())\n\t\tcursor = addDaysInTz(cursor, -1, tz)\n\t}\n\treturn isoDays.reverse().map((date) => ({ date, value: byDay.get(date) ?? 0 }))\n}\n\n/**\n * Project a comparison series onto the primary axis: day i of the previous window overlays\n * day i of the current one. Both windows span the same day count by construction, so this\n * only guards a DST-shifted or clamped edge, silently truncating or zero-filling; a filled\n * bucket borrows the axis day so every point still carries a real date.\n */\nconst alignSeries = (points: SeriesPoint[], axis: SeriesPoint[]): SeriesPoint[] =>\n\tpoints.length === axis.length\n\t\t? points\n\t\t: axis.map((day, i) => points[i] ?? { date: day.date, value: 0 })\n\n/**\n * Site-wide time-series read for a trend widget: resolve the timeframe, pick the\n * adapter, gate on the metric and day-granularity support, read through the engine,\n * then return a zero-filled daily series plus the headline total. Mirrors\n * `readForWidget` but yields points instead of a single value.\n */\nexport const readForWidgetSeries = async (\n\targs: ReadForWidgetSeriesArgs\n): Promise<WidgetSeriesResult> => {\n\tconst { req, metric, timeframe, adapterId, now, range, filters, compare } = args\n\n\tconst prepared = await prepareWidgetRead({\n\t\treq,\n\t\tnow,\n\t\ttimeframe,\n\t\tadapterId,\n\t\tscope: args.scope,\n\t\ttimezone: args.timezone,\n\t\trange,\n\t\tfilters,\n\t\trequires: { metrics: [metric] },\n\t\tgranularity: 'day',\n\t\tgoalRead: () => ({ metrics: [metric] }),\n\t})\n\tif (!prepared.ok) {\n\t\treturn {\n\t\t\tstatus: prepared.status,\n\t\t\tadapterId: prepared.adapterId,\n\t\t\tdateRange: prepared.dateRange,\n\t\t\ttimezone: prepared.tz,\n\t\t\tpoints: [],\n\t\t\ttotal: 0,\n\t\t}\n\t}\n\tconst { runtime, adapter, tz, dateRange, goalSlugs } = prepared\n\tconst base = { dateRange, timezone: tz, points: [] as SeriesPoint[], total: 0 }\n\tconst previousRange =\n\t\truntime.comparison && comparisonOf(adapter.capabilities) ? previousWindow(dateRange, tz) : null\n\tconst comparisonRange =\n\t\tpreviousRange &&\n\t\twithinLookback(previousRange, adapter.capabilities.maxLookbackDays, { tz, now })\n\t\t\t? previousRange\n\t\t\t: undefined\n\tconst readBase = {\n\t\tmetrics: [metric],\n\t\tfilters,\n\t\ttimezone: tz,\n\t\tscope: prepared.queryScope,\n\t\t...(goalSlugs === undefined ? {} : { goalSlugs }),\n\t}\n\tlet result: AnalyticsResult\n\tlet previous: AnalyticsResult | undefined\n\ttry {\n\t\t;[result, previous] = await Promise.all([\n\t\t\truntime.engine.read(adapter, { ...readBase, dateRange, granularity: 'day' }),\n\t\t\tcomparisonRange\n\t\t\t\t? runtime.engine.read(adapter, {\n\t\t\t\t\t\t...readBase,\n\t\t\t\t\t\tdateRange: comparisonRange,\n\t\t\t\t\t\t// The overlay needs the previous window bucketed like the primary; the delta\n\t\t\t\t\t\t// alone only needs its total, so the read stays as it was without `compare`.\n\t\t\t\t\t\t...(compare ? { granularity: 'day' as const } : {}),\n\t\t\t\t\t})\n\t\t\t\t: undefined,\n\t\t])\n\t} catch {\n\t\t// No cache entry (fresh or stale) survived the failed read; degrade like an\n\t\t// unsupported capability instead of throwing through the widget render tree.\n\t\treturn { status: 'unavailable', adapterId: adapter.id, ...base }\n\t}\n\tconst previousTotal = previous ? previous.totals?.[metric] : undefined\n\tconst points = fillDailySeries({ rows: result.rows, dateRange, metric, tz })\n\treturn {\n\t\tstatus: 'ok',\n\t\tadapterId: adapter.id,\n\t\tdateRange,\n\t\ttimezone: tz,\n\t\tpoints,\n\t\ttotal: result.totals?.[metric] ?? 0,\n\t\t...readMeta(result),\n\t\tpreviousTotal,\n\t\tcomparisonRange,\n\t\t...(compare && previous && comparisonRange\n\t\t\t? {\n\t\t\t\t\tcomparisonPoints: alignSeries(\n\t\t\t\t\t\tfillDailySeries({ rows: previous.rows, dateRange: comparisonRange, metric, tz }),\n\t\t\t\t\t\tpoints\n\t\t\t\t\t),\n\t\t\t\t}\n\t\t\t: {}),\n\t}\n}\n"],"mappings":"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"}
@@ -0,0 +1,18 @@
1
+ //#region src/widgets/readMeta.ts
2
+ /**
3
+ * One mapping from an adapter result's meta to the flags a widget renders. Every helper
4
+ * maps all of them, so a widget that starts rendering a notice needs nothing from the read
5
+ * path, and a flag cannot go missing on one widget while its neighbour shows it.
6
+ */
7
+ const readMeta = (result) => ({
8
+ clamped: result.meta.clamped ?? false,
9
+ stale: result.meta.stale ?? false,
10
+ filtersUnapplied: (result.meta.unappliedFilters?.length ?? 0) > 0,
11
+ goalsUnresolved: result.meta.goalsUnresolved === true,
12
+ sampled: result.meta.sampled ?? false,
13
+ provider: result.meta.provider
14
+ });
15
+ //#endregion
16
+ export { readMeta };
17
+
18
+ //# sourceMappingURL=readMeta.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"readMeta.js","names":[],"sources":["../../src/widgets/readMeta.ts"],"sourcesContent":["import type { AnalyticsResult } from '../core/contract'\n\n/** The state flags every widget result carries, whatever shape its numbers take. */\nexport interface WidgetReadMeta {\n\t/** The source read a shorter window than the one that was asked for. */\n\tclamped: boolean\n\t/** The engine served an expired cache entry after a failed provider read. */\n\tstale: boolean\n\t/** The source answered without one of the filters the read carried. */\n\tfiltersUnapplied: boolean\n\t/** The source could not read the scope's goals, so the goal numbers mean nothing. */\n\tgoalsUnresolved: boolean\n\t/** The read hit the source's event scan cap, so the numbers are a floor. */\n\tsampled: boolean\n\t/** The source that answered. */\n\tprovider: string\n}\n\n/**\n * One mapping from an adapter result's meta to the flags a widget renders. Every helper\n * maps all of them, so a widget that starts rendering a notice needs nothing from the read\n * path, and a flag cannot go missing on one widget while its neighbour shows it.\n */\nexport const readMeta = (result: AnalyticsResult): WidgetReadMeta => ({\n\tclamped: result.meta.clamped ?? false,\n\tstale: result.meta.stale ?? false,\n\tfiltersUnapplied: (result.meta.unappliedFilters?.length ?? 0) > 0,\n\tgoalsUnresolved: result.meta.goalsUnresolved === true,\n\tsampled: result.meta.sampled ?? false,\n\tprovider: result.meta.provider,\n})\n"],"mappings":";;;;;;AAuBA,MAAa,YAAY,YAA6C;CACrE,SAAS,OAAO,KAAK,WAAW;CAChC,OAAO,OAAO,KAAK,SAAS;CAC5B,mBAAmB,OAAO,KAAK,kBAAkB,UAAU,KAAK;CAChE,iBAAiB,OAAO,KAAK,oBAAoB;CACjD,SAAS,OAAO,KAAK,WAAW;CAChC,UAAU,OAAO,KAAK;AACvB"}
@@ -1,4 +1,5 @@
1
1
  import { REALTIME_PATH } from "../plugin/paths.js";
2
+ import { readResponseError } from "../plugin/errors.js";
2
3
  //#region src/widgets/realtimePoll.ts
3
4
  /** Build the realtime endpoint's base URL from the app's configured API route, not a hardcoded `/api`. */
4
5
  const buildRealtimeEndpoint = (serverURL, apiRoute) => `${serverURL ?? ""}${apiRoute}${REALTIME_PATH}`;
@@ -11,6 +12,17 @@ const buildPollPath = (endpoint, config) => {
11
12
  if (config.dataSource) params.set("dataSource", config.dataSource);
12
13
  return `${endpoint}?${params.toString()}`;
13
14
  };
15
+ /** Codes no later tick can talk its way out of, so the poller stops rather than repeats. */
16
+ const TERMINAL = new Set(["unauthorized", "forbidden"]);
17
+ /**
18
+ * Whether a refused poll is worth repeating. A provider outage, an unreadable answer and a
19
+ * legacy body all keep polling, since the next tick may well succeed; only a refusal aimed
20
+ * at this reader is final. The counter shows the same paused state either way.
21
+ */
22
+ const isPollRefusalFinal = async (res) => {
23
+ const code = (await readResponseError(res))?.code;
24
+ return code !== void 0 && TERMINAL.has(code);
25
+ };
14
26
  /** Map a minute series to TrendChart points (HH:MM labels, locale-formatted values). */
15
27
  const toRealtimePoints = (series, locale) => {
16
28
  const nf = new Intl.NumberFormat(locale);
@@ -24,6 +36,6 @@ const toRealtimePoints = (series, locale) => {
24
36
  }));
25
37
  };
26
38
  //#endregion
27
- export { buildPollPath, buildRealtimeEndpoint, toRealtimePoints };
39
+ export { buildPollPath, buildRealtimeEndpoint, isPollRefusalFinal, toRealtimePoints };
28
40
 
29
41
  //# sourceMappingURL=realtimePoll.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"realtimePoll.js","names":[],"sources":["../../src/widgets/realtimePoll.ts"],"sourcesContent":["import { REALTIME_PATH } from '../plugin/paths'\nimport type { RealtimePoint } from './readForWidgetRealtime'\n\nexport interface PollConfig {\n\tmetric: string\n\twindowMinutes: number\n\tdataSource?: string\n}\n\nexport interface RealtimeChartPoint {\n\tlabel: string\n\tvalue: number\n\tdisplay: string\n}\n\n/** Build the realtime endpoint's base URL from the app's configured API route, not a hardcoded `/api`. */\nexport const buildRealtimeEndpoint = (serverURL: string | undefined, apiRoute: string): string =>\n\t`${serverURL ?? ''}${apiRoute}${REALTIME_PATH}`\n\n/** Build the realtime endpoint path + query string for a poll. */\nexport const buildPollPath = (endpoint: string, config: PollConfig): string => {\n\tconst params = new URLSearchParams({\n\t\tmetric: config.metric,\n\t\twindowMinutes: String(config.windowMinutes),\n\t})\n\tif (config.dataSource) {\n\t\tparams.set('dataSource', config.dataSource)\n\t}\n\treturn `${endpoint}?${params.toString()}`\n}\n\n/** Map a minute series to TrendChart points (HH:MM labels, locale-formatted values). */\nexport const toRealtimePoints = (series: RealtimePoint[], locale: string): RealtimeChartPoint[] => {\n\tconst nf = new Intl.NumberFormat(locale)\n\treturn series.map((p) => ({\n\t\tlabel: new Date(p.date).toLocaleTimeString(locale, { hour: '2-digit', minute: '2-digit' }),\n\t\tvalue: p.value,\n\t\tdisplay: nf.format(p.value),\n\t}))\n}\n"],"mappings":";;;AAgBA,MAAa,yBAAyB,WAA+B,aACpE,GAAG,aAAa,KAAK,WAAW;;AAGjC,MAAa,iBAAiB,UAAkB,WAA+B;CAC9E,MAAM,SAAS,IAAI,gBAAgB;EAClC,QAAQ,OAAO;EACf,eAAe,OAAO,OAAO,aAAa;CAC3C,CAAC;CACD,IAAI,OAAO,YACV,OAAO,IAAI,cAAc,OAAO,UAAU;CAE3C,OAAO,GAAG,SAAS,GAAG,OAAO,SAAS;AACvC;;AAGA,MAAa,oBAAoB,QAAyB,WAAyC;CAClG,MAAM,KAAK,IAAI,KAAK,aAAa,MAAM;CACvC,OAAO,OAAO,KAAK,OAAO;EACzB,OAAO,IAAI,KAAK,EAAE,IAAI,EAAE,mBAAmB,QAAQ;GAAE,MAAM;GAAW,QAAQ;EAAU,CAAC;EACzF,OAAO,EAAE;EACT,SAAS,GAAG,OAAO,EAAE,KAAK;CAC3B,EAAE;AACH"}
1
+ {"version":3,"file":"realtimePoll.js","names":[],"sources":["../../src/widgets/realtimePoll.ts"],"sourcesContent":["import { type AnalyticsErrorCode, readResponseError } from '../plugin/errors'\nimport { REALTIME_PATH } from '../plugin/paths'\nimport type { RealtimePoint } from './readForWidgetRealtime'\n\nexport interface PollConfig {\n\tmetric: string\n\twindowMinutes: number\n\tdataSource?: string\n}\n\nexport interface RealtimeChartPoint {\n\tlabel: string\n\tvalue: number\n\tdisplay: string\n}\n\n/** Build the realtime endpoint's base URL from the app's configured API route, not a hardcoded `/api`. */\nexport const buildRealtimeEndpoint = (serverURL: string | undefined, apiRoute: string): string =>\n\t`${serverURL ?? ''}${apiRoute}${REALTIME_PATH}`\n\n/** Build the realtime endpoint path + query string for a poll. */\nexport const buildPollPath = (endpoint: string, config: PollConfig): string => {\n\tconst params = new URLSearchParams({\n\t\tmetric: config.metric,\n\t\twindowMinutes: String(config.windowMinutes),\n\t})\n\tif (config.dataSource) {\n\t\tparams.set('dataSource', config.dataSource)\n\t}\n\treturn `${endpoint}?${params.toString()}`\n}\n\n/** Codes no later tick can talk its way out of, so the poller stops rather than repeats. */\nconst TERMINAL: ReadonlySet<AnalyticsErrorCode> = new Set<AnalyticsErrorCode>([\n\t'unauthorized',\n\t'forbidden',\n])\n\n/**\n * Whether a refused poll is worth repeating. A provider outage, an unreadable answer and a\n * legacy body all keep polling, since the next tick may well succeed; only a refusal aimed\n * at this reader is final. The counter shows the same paused state either way.\n */\nexport const isPollRefusalFinal = async (res: Response): Promise<boolean> => {\n\tconst code = (await readResponseError(res))?.code\n\treturn code !== undefined && TERMINAL.has(code)\n}\n\n/** Map a minute series to TrendChart points (HH:MM labels, locale-formatted values). */\nexport const toRealtimePoints = (series: RealtimePoint[], locale: string): RealtimeChartPoint[] => {\n\tconst nf = new Intl.NumberFormat(locale)\n\treturn series.map((p) => ({\n\t\tlabel: new Date(p.date).toLocaleTimeString(locale, { hour: '2-digit', minute: '2-digit' }),\n\t\tvalue: p.value,\n\t\tdisplay: nf.format(p.value),\n\t}))\n}\n"],"mappings":";;;;AAiBA,MAAa,yBAAyB,WAA+B,aACpE,GAAG,aAAa,KAAK,WAAW;;AAGjC,MAAa,iBAAiB,UAAkB,WAA+B;CAC9E,MAAM,SAAS,IAAI,gBAAgB;EAClC,QAAQ,OAAO;EACf,eAAe,OAAO,OAAO,aAAa;CAC3C,CAAC;CACD,IAAI,OAAO,YACV,OAAO,IAAI,cAAc,OAAO,UAAU;CAE3C,OAAO,GAAG,SAAS,GAAG,OAAO,SAAS;AACvC;;AAGA,MAAM,WAA4C,IAAI,IAAwB,CAC7E,gBACA,WACD,CAAC;;;;;;AAOD,MAAa,qBAAqB,OAAO,QAAoC;CAC5E,MAAM,QAAQ,MAAM,kBAAkB,GAAG,IAAI;CAC7C,OAAO,SAAS,KAAA,KAAa,SAAS,IAAI,IAAI;AAC/C;;AAGA,MAAa,oBAAoB,QAAyB,WAAyC;CAClG,MAAM,KAAK,IAAI,KAAK,aAAa,MAAM;CACvC,OAAO,OAAO,KAAK,OAAO;EACzB,OAAO,IAAI,KAAK,EAAE,IAAI,EAAE,mBAAmB,QAAQ;GAAE,MAAM;GAAW,QAAQ;EAAU,CAAC;EACzF,OAAO,EAAE;EACT,SAAS,GAAG,OAAO,EAAE,KAAK;CAC3B,EAAE;AACH"}