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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (521) hide show
  1. package/CHANGELOG.md +280 -0
  2. package/LICENSE +21 -21
  3. package/README.md +15 -4
  4. package/dist/adapters/ga4/disableKey.d.ts +9 -0
  5. package/dist/adapters/ga4/disableKey.js +21 -0
  6. package/dist/adapters/ga4/disableKey.js.map +1 -0
  7. package/dist/adapters/ga4/eventName.d.ts +15 -0
  8. package/dist/adapters/ga4/eventName.js +19 -0
  9. package/dist/adapters/ga4/eventName.js.map +1 -0
  10. package/dist/adapters/ga4/ga4.d.ts +5 -0
  11. package/dist/adapters/ga4/ga4.js +186 -58
  12. package/dist/adapters/ga4/ga4.js.map +1 -1
  13. package/dist/adapters/ga4/measurementId.js +15 -0
  14. package/dist/adapters/ga4/measurementId.js.map +1 -0
  15. package/dist/adapters/goalRead.js +126 -0
  16. package/dist/adapters/goalRead.js.map +1 -0
  17. package/dist/adapters/http/fetchJson.js +1 -1
  18. package/dist/adapters/plausible/plausible.d.ts +25 -0
  19. package/dist/adapters/plausible/plausible.js +159 -38
  20. package/dist/adapters/plausible/plausible.js.map +1 -1
  21. package/dist/adapters/posthog/posthog.d.ts +10 -1
  22. package/dist/adapters/posthog/posthog.js +130 -21
  23. package/dist/adapters/posthog/posthog.js.map +1 -1
  24. package/dist/adapters/series.js +11 -1
  25. package/dist/adapters/series.js.map +1 -1
  26. package/dist/adapters/umami/umami.d.ts +13 -1
  27. package/dist/adapters/umami/umami.js +278 -26
  28. package/dist/adapters/umami/umami.js.map +1 -1
  29. package/dist/binding/resolvePath.js +18 -2
  30. package/dist/binding/resolvePath.js.map +1 -1
  31. package/dist/capture/getTrackerConfig.d.ts +20 -0
  32. package/dist/capture/getTrackerConfig.js +31 -0
  33. package/dist/capture/getTrackerConfig.js.map +1 -0
  34. package/dist/capture/mountPath.js +14 -0
  35. package/dist/capture/mountPath.js.map +1 -0
  36. package/dist/capture/proxyEndpoint.js +127 -0
  37. package/dist/capture/proxyEndpoint.js.map +1 -0
  38. package/dist/capture/proxyRoutes.js +108 -0
  39. package/dist/capture/proxyRoutes.js.map +1 -0
  40. package/dist/capture/requestBody.js +68 -0
  41. package/dist/capture/requestBody.js.map +1 -0
  42. package/dist/capture/slots.d.ts +8 -0
  43. package/dist/capture/slots.js +54 -0
  44. package/dist/capture/slots.js.map +1 -0
  45. package/dist/capture/trackerConfig.d.ts +33 -0
  46. package/dist/capture/trackerConfig.js +95 -0
  47. package/dist/capture/trackerConfig.js.map +1 -0
  48. package/dist/capture/trackerEndpoint.js +35 -0
  49. package/dist/capture/trackerEndpoint.js.map +1 -0
  50. package/dist/charts/BarList.d.ts +16 -1
  51. package/dist/charts/BarList.js +41 -19
  52. package/dist/charts/BarList.js.map +1 -1
  53. package/dist/charts/TrendChart.d.ts +16 -3
  54. package/dist/charts/TrendChart.js +172 -106
  55. package/dist/charts/TrendChart.js.map +1 -1
  56. package/dist/charts/bars.d.ts +4 -0
  57. package/dist/charts/bars.js +3 -1
  58. package/dist/charts/bars.js.map +1 -1
  59. package/dist/charts/bucket.js +10 -1
  60. package/dist/charts/bucket.js.map +1 -1
  61. package/dist/charts/spline.js +2 -2
  62. package/dist/charts/spline.js.map +1 -1
  63. package/dist/charts/styles.js +18 -1
  64. package/dist/charts/styles.js.map +1 -1
  65. package/dist/core/cacheKey.js +26 -3
  66. package/dist/core/cacheKey.js.map +1 -1
  67. package/dist/core/capabilities.d.ts +17 -2
  68. package/dist/core/capabilities.js +20 -1
  69. package/dist/core/capabilities.js.map +1 -1
  70. package/dist/core/capture.d.ts +49 -0
  71. package/dist/core/contract.d.ts +74 -5
  72. package/dist/core/contract.js +30 -1
  73. package/dist/core/contract.js.map +1 -1
  74. package/dist/core/granularity.js +1 -1
  75. package/dist/core/options.d.ts +168 -8
  76. package/dist/core/options.js +132 -4
  77. package/dist/core/options.js.map +1 -1
  78. package/dist/core/registry.d.ts +1 -0
  79. package/dist/core/scopeList.js +32 -0
  80. package/dist/core/scopeList.js.map +1 -0
  81. package/dist/core/scopedRead.js +101 -29
  82. package/dist/core/scopedRead.js.map +1 -1
  83. package/dist/core/serverEvent.d.ts +60 -0
  84. package/dist/core/serverEvent.js +12 -0
  85. package/dist/core/serverEvent.js.map +1 -0
  86. package/dist/exports/adapters/ga4.d.ts +2 -1
  87. package/dist/exports/adapters/ga4.js +2 -1
  88. package/dist/exports/adapters/native.d.ts +3 -1
  89. package/dist/exports/adapters/native.js +2 -1
  90. package/dist/exports/client.d.ts +16 -2
  91. package/dist/exports/client.js +13 -1
  92. package/dist/exports/geo.d.ts +2 -2
  93. package/dist/exports/next.d.ts +2 -1
  94. package/dist/exports/next.js +2 -1
  95. package/dist/exports/react.d.ts +4 -0
  96. package/dist/exports/react.js +5 -0
  97. package/dist/exports/rsc.d.ts +12 -4
  98. package/dist/exports/rsc.js +7 -2
  99. package/dist/exports/tracker.d.ts +21 -0
  100. package/dist/exports/tracker.js +15 -0
  101. package/dist/exports/types.d.ts +17 -3
  102. package/dist/exports/types.js +4 -2
  103. package/dist/fields/AnalyticsPanelClient.js +2 -2
  104. package/dist/fields/AnalyticsPanelField.js +1 -1
  105. package/dist/fields/AnalyticsStatField.js +2 -2
  106. package/dist/fields/config/FilterDimensionSelectField.d.ts +14 -0
  107. package/dist/fields/config/FilterDimensionSelectField.js +77 -0
  108. package/dist/fields/config/FilterDimensionSelectField.js.map +1 -0
  109. package/dist/fields/config/FilterOperatorSelectField.d.ts +14 -0
  110. package/dist/fields/config/FilterOperatorSelectField.js +75 -0
  111. package/dist/fields/config/FilterOperatorSelectField.js.map +1 -0
  112. package/dist/fields/config/MetricSelectField.d.ts +23 -0
  113. package/dist/fields/config/MetricSelectField.js +51 -0
  114. package/dist/fields/config/MetricSelectField.js.map +1 -0
  115. package/dist/fields/config/SourceSelectField.d.ts +14 -0
  116. package/dist/fields/config/SourceSelectField.js +46 -0
  117. package/dist/fields/config/SourceSelectField.js.map +1 -0
  118. package/dist/fields/config/fetchSources.d.ts +16 -0
  119. package/dist/fields/config/fetchSources.js +33 -0
  120. package/dist/fields/config/fetchSources.js.map +1 -0
  121. package/dist/fields/config/narrow.js +32 -0
  122. package/dist/fields/config/narrow.js.map +1 -0
  123. package/dist/fields/config/sourcesState.js +27 -0
  124. package/dist/fields/config/sourcesState.js.map +1 -0
  125. package/dist/fields/config/toSelectOption.js +27 -0
  126. package/dist/fields/config/toSelectOption.js.map +1 -0
  127. package/dist/fields/config/useAnalyticsSources.d.ts +24 -0
  128. package/dist/fields/config/useAnalyticsSources.js +62 -0
  129. package/dist/fields/config/useAnalyticsSources.js.map +1 -0
  130. package/dist/fields/config/useFilterCapabilities.d.ts +28 -0
  131. package/dist/fields/config/useFilterCapabilities.js +52 -0
  132. package/dist/fields/config/useFilterCapabilities.js.map +1 -0
  133. package/dist/fields/readForDocument.d.ts +5 -0
  134. package/dist/fields/readForDocument.js +22 -10
  135. package/dist/fields/readForDocument.js.map +1 -1
  136. package/dist/goals/GoalSelectField.d.ts +7 -0
  137. package/dist/goals/GoalSelectField.js +77 -0
  138. package/dist/goals/GoalSelectField.js.map +1 -0
  139. package/dist/goals/collection.js +254 -0
  140. package/dist/goals/collection.js.map +1 -0
  141. package/dist/goals/currency.js +14 -0
  142. package/dist/goals/currency.js.map +1 -0
  143. package/dist/goals/fetchGoals.d.ts +18 -0
  144. package/dist/goals/fetchGoals.js +33 -0
  145. package/dist/goals/fetchGoals.js.map +1 -0
  146. package/dist/goals/goalField.d.ts +31 -0
  147. package/dist/goals/goalField.js +56 -0
  148. package/dist/goals/goalField.js.map +1 -0
  149. package/dist/goals/goalsEndpoint.d.ts +1 -0
  150. package/dist/goals/goalsEndpoint.js +58 -0
  151. package/dist/goals/goalsEndpoint.js.map +1 -0
  152. package/dist/goals/match.js +64 -0
  153. package/dist/goals/match.js.map +1 -0
  154. package/dist/goals/resolver.d.ts +8 -0
  155. package/dist/goals/resolver.js +147 -0
  156. package/dist/goals/resolver.js.map +1 -0
  157. package/dist/goals/trackGoalAction.d.ts +76 -0
  158. package/dist/goals/trackGoalAction.js +158 -0
  159. package/dist/goals/trackGoalAction.js.map +1 -0
  160. package/dist/goals/types.d.ts +33 -0
  161. package/dist/goals/types.js +7 -0
  162. package/dist/goals/types.js.map +1 -0
  163. package/dist/goals/useAnalyticsGoals.d.ts +20 -0
  164. package/dist/goals/useAnalyticsGoals.js +67 -0
  165. package/dist/goals/useAnalyticsGoals.js.map +1 -0
  166. package/dist/index.d.ts +14 -3
  167. package/dist/index.js +185 -19
  168. package/dist/index.js.map +1 -1
  169. package/dist/native/collections/events.js +65 -1
  170. package/dist/native/collections/events.js.map +1 -1
  171. package/dist/native/collections/rollups.js +39 -3
  172. package/dist/native/collections/rollups.js.map +1 -1
  173. package/dist/native/eventScan.js +25 -0
  174. package/dist/native/eventScan.js.map +1 -0
  175. package/dist/native/geo/composeGeoResolvers.js +2 -2
  176. package/dist/native/geo/composeGeoResolvers.js.map +1 -1
  177. package/dist/native/geo/geoResolver.d.ts +9 -2
  178. package/dist/native/geo/geoResolver.js.map +1 -1
  179. package/dist/native/geo/maxmindResolver.js +3 -5
  180. package/dist/native/geo/maxmindResolver.js.map +1 -1
  181. package/dist/native/ingest/bots.d.ts +11 -0
  182. package/dist/native/ingest/bots.js +71 -0
  183. package/dist/native/ingest/bots.js.map +1 -0
  184. package/dist/native/ingest/browser.js +47 -0
  185. package/dist/native/ingest/browser.js.map +1 -0
  186. package/dist/native/ingest/clientIp.js +20 -0
  187. package/dist/native/ingest/clientIp.js.map +1 -0
  188. package/dist/native/ingest/device.js +11 -3
  189. package/dist/native/ingest/device.js.map +1 -1
  190. package/dist/native/ingest/endpoint.d.ts +1 -0
  191. package/dist/native/ingest/endpoint.js +107 -21
  192. package/dist/native/ingest/endpoint.js.map +1 -1
  193. package/dist/native/ingest/flushBatch.js +29 -38
  194. package/dist/native/ingest/flushBatch.js.map +1 -1
  195. package/dist/native/ingest/language.js +14 -0
  196. package/dist/native/ingest/language.js.map +1 -0
  197. package/dist/native/ingest/normalizeEvent.d.ts +30 -0
  198. package/dist/native/ingest/normalizeEvent.js +115 -16
  199. package/dist/native/ingest/normalizeEvent.js.map +1 -1
  200. package/dist/native/ingest/referrer.js +48 -0
  201. package/dist/native/ingest/referrer.js.map +1 -0
  202. package/dist/native/ingest/requestHost.js +57 -0
  203. package/dist/native/ingest/requestHost.js.map +1 -0
  204. package/dist/native/ingest/resolveHostname.d.ts +29 -0
  205. package/dist/native/ingest/resolveHostname.js +52 -0
  206. package/dist/native/ingest/resolveHostname.js.map +1 -0
  207. package/dist/native/ingest/salt.js +27 -2
  208. package/dist/native/ingest/salt.js.map +1 -1
  209. package/dist/native/ingest/serverTrack.d.ts +20 -0
  210. package/dist/native/ingest/serverTrack.js +109 -0
  211. package/dist/native/ingest/serverTrack.js.map +1 -0
  212. package/dist/native/ingest/source.d.ts +11 -0
  213. package/dist/native/ingest/source.js +264 -16
  214. package/dist/native/ingest/source.js.map +1 -1
  215. package/dist/native/ingest/utm.js +33 -0
  216. package/dist/native/ingest/utm.js.map +1 -0
  217. package/dist/native/ingest/validate.js +26 -0
  218. package/dist/native/ingest/validate.js.map +1 -0
  219. package/dist/native/nativeAdapter.d.ts +37 -1
  220. package/dist/native/nativeAdapter.js +175 -22
  221. package/dist/native/nativeAdapter.js.map +1 -1
  222. package/dist/native/query/eventAgg.js +175 -0
  223. package/dist/native/query/eventAgg.js.map +1 -0
  224. package/dist/native/retention/pruneTask.js +53 -13
  225. package/dist/native/retention/pruneTask.js.map +1 -1
  226. package/dist/native/rollupAcc.js +12 -1
  227. package/dist/native/rollupAcc.js.map +1 -1
  228. package/dist/native/rollups/bucketKey.js +15 -0
  229. package/dist/native/rollups/bucketKey.js.map +1 -0
  230. package/dist/native/rollups/bumpRollups.js +116 -0
  231. package/dist/native/rollups/bumpRollups.js.map +1 -0
  232. package/dist/native/rollups/deltas.js +86 -11
  233. package/dist/native/rollups/deltas.js.map +1 -1
  234. package/dist/native/rollups/insertManyIfNew.js +93 -0
  235. package/dist/native/rollups/insertManyIfNew.js.map +1 -0
  236. package/dist/next/captureRewrites.d.ts +42 -0
  237. package/dist/next/captureRewrites.js +57 -0
  238. package/dist/next/captureRewrites.js.map +1 -0
  239. package/dist/next/posthogProxyRewrites.d.ts +5 -0
  240. package/dist/next/posthogProxyRewrites.js +16 -21
  241. package/dist/next/posthogProxyRewrites.js.map +1 -1
  242. package/dist/plugin/documentEndpoint.js +71 -24
  243. package/dist/plugin/documentEndpoint.js.map +1 -1
  244. package/dist/plugin/errors.d.ts +31 -0
  245. package/dist/plugin/errors.js +79 -0
  246. package/dist/plugin/errors.js.map +1 -0
  247. package/dist/plugin/goalHint.d.ts +1 -0
  248. package/dist/plugin/goalHint.js +24 -0
  249. package/dist/plugin/goalHint.js.map +1 -0
  250. package/dist/plugin/paths.js +19 -1
  251. package/dist/plugin/paths.js.map +1 -1
  252. package/dist/plugin/queryEndpoint.js +124 -0
  253. package/dist/plugin/queryEndpoint.js.map +1 -0
  254. package/dist/plugin/readContextForRequest.js +73 -0
  255. package/dist/plugin/readContextForRequest.js.map +1 -0
  256. package/dist/plugin/realtimeEndpoint.js +39 -18
  257. package/dist/plugin/realtimeEndpoint.js.map +1 -1
  258. package/dist/plugin/refreshEndpoint.js +113 -0
  259. package/dist/plugin/refreshEndpoint.js.map +1 -0
  260. package/dist/plugin/runtime.d.ts +1 -0
  261. package/dist/plugin/runtime.js +33 -1
  262. package/dist/plugin/runtime.js.map +1 -1
  263. package/dist/plugin/scopeChange.js +22 -0
  264. package/dist/plugin/scopeChange.js.map +1 -0
  265. package/dist/plugin/scopeFieldBoot.js +22 -0
  266. package/dist/plugin/scopeFieldBoot.js.map +1 -0
  267. package/dist/plugin/sourcesEndpoint.js +28 -0
  268. package/dist/plugin/sourcesEndpoint.js.map +1 -0
  269. package/dist/plugin/warmTask.js +0 -0
  270. package/dist/plugin/warmTask.js.map +1 -1
  271. package/dist/providers/access.js +2 -1
  272. package/dist/providers/access.js.map +1 -1
  273. package/dist/providers/collection.js +90 -29
  274. package/dist/providers/collection.js.map +1 -1
  275. package/dist/providers/factory.js +11 -3
  276. package/dist/providers/factory.js.map +1 -1
  277. package/dist/providers/resolver.js.map +1 -1
  278. package/dist/query/dates.js +64 -0
  279. package/dist/query/dates.js.map +1 -0
  280. package/dist/query/errors.d.ts +14 -0
  281. package/dist/query/fetchQuery.d.ts +79 -0
  282. package/dist/query/fetchQuery.js +117 -0
  283. package/dist/query/fetchQuery.js.map +1 -0
  284. package/dist/query/parse.d.ts +22 -0
  285. package/dist/query/parse.js +168 -0
  286. package/dist/query/parse.js.map +1 -0
  287. package/dist/query/response.d.ts +39 -0
  288. package/dist/query/response.js +11 -0
  289. package/dist/query/response.js.map +1 -0
  290. package/dist/react/AnalyticsProvider.d.ts +50 -0
  291. package/dist/react/AnalyticsProvider.js +67 -0
  292. package/dist/react/AnalyticsProvider.js.map +1 -0
  293. package/dist/react/TrackerBoot.d.ts +22 -0
  294. package/dist/react/TrackerBoot.js +30 -0
  295. package/dist/react/TrackerBoot.js.map +1 -0
  296. package/dist/react/useAnalytics.d.ts +20 -0
  297. package/dist/react/useAnalytics.js +52 -0
  298. package/dist/react/useAnalytics.js.map +1 -0
  299. package/dist/rsc/AnalyticsScripts.d.ts +30 -0
  300. package/dist/rsc/AnalyticsScripts.js +41 -0
  301. package/dist/rsc/AnalyticsScripts.js.map +1 -0
  302. package/dist/surfacing/cacheStore.d.ts +1 -0
  303. package/dist/surfacing/cacheStore.js +18 -2
  304. package/dist/surfacing/cacheStore.js.map +1 -1
  305. package/dist/surfacing/engine.d.ts +1 -0
  306. package/dist/surfacing/engine.js +47 -6
  307. package/dist/surfacing/engine.js.map +1 -1
  308. package/dist/surfacing/epoch.d.ts +1 -0
  309. package/dist/surfacing/epoch.js +72 -0
  310. package/dist/surfacing/epoch.js.map +1 -0
  311. package/dist/surfacing/queue.js +22 -6
  312. package/dist/surfacing/queue.js.map +1 -1
  313. package/dist/surfacing/rateLimiter.js +130 -0
  314. package/dist/surfacing/rateLimiter.js.map +1 -0
  315. package/dist/surfacing/retryPolicy.js +15 -0
  316. package/dist/surfacing/retryPolicy.js.map +1 -0
  317. package/dist/sync/collection.js +23 -7
  318. package/dist/sync/collection.js.map +1 -1
  319. package/dist/sync/syncTask.js +68 -33
  320. package/dist/sync/syncTask.js.map +1 -1
  321. package/dist/testing/memoryAdapter.d.ts +2 -0
  322. package/dist/testing/memoryAdapter.js +17 -1
  323. package/dist/testing/memoryAdapter.js.map +1 -1
  324. package/dist/timeframe/tz.js +17 -6
  325. package/dist/timeframe/tz.js.map +1 -1
  326. package/dist/tracker/autoCapture.d.ts +48 -0
  327. package/dist/tracker/autoCapture.js +129 -0
  328. package/dist/tracker/autoCapture.js.map +1 -0
  329. package/dist/tracker/consent.d.ts +24 -0
  330. package/dist/tracker/consent.js +48 -0
  331. package/dist/tracker/consent.js.map +1 -0
  332. package/dist/tracker/createTracker.d.ts +18 -0
  333. package/dist/tracker/createTracker.js +215 -0
  334. package/dist/tracker/createTracker.js.map +1 -0
  335. package/dist/tracker/exclusion.d.ts +28 -0
  336. package/dist/tracker/exclusion.js +50 -0
  337. package/dist/tracker/exclusion.js.map +1 -0
  338. package/dist/tracker/initTracker.d.ts +22 -0
  339. package/dist/tracker/initTracker.js +33 -0
  340. package/dist/tracker/initTracker.js.map +1 -0
  341. package/dist/tracker/loadScript.d.ts +14 -0
  342. package/dist/tracker/loadScript.js +41 -0
  343. package/dist/tracker/loadScript.js.map +1 -0
  344. package/dist/tracker/pageTracking.d.ts +17 -0
  345. package/dist/tracker/pageTracking.js +38 -0
  346. package/dist/tracker/pageTracking.js.map +1 -0
  347. package/dist/tracker/registry.d.ts +27 -0
  348. package/dist/tracker/registry.js +73 -0
  349. package/dist/tracker/registry.js.map +1 -0
  350. package/dist/tracker/sinks/ga4.d.ts +29 -0
  351. package/dist/tracker/sinks/ga4.js +30 -0
  352. package/dist/tracker/sinks/ga4.js.map +1 -0
  353. package/dist/tracker/sinks/native.d.ts +22 -0
  354. package/dist/tracker/sinks/native.js +56 -0
  355. package/dist/tracker/sinks/native.js.map +1 -0
  356. package/dist/tracker/sinks/plausible.d.ts +20 -0
  357. package/dist/tracker/sinks/plausible.js +32 -0
  358. package/dist/tracker/sinks/plausible.js.map +1 -0
  359. package/dist/tracker/sinks/posthog.d.ts +18 -0
  360. package/dist/tracker/sinks/posthog.js +30 -0
  361. package/dist/tracker/sinks/posthog.js.map +1 -0
  362. package/dist/tracker/sinks/umami.d.ts +18 -0
  363. package/dist/tracker/sinks/umami.js +23 -0
  364. package/dist/tracker/sinks/umami.js.map +1 -0
  365. package/dist/tracker/sinks/vendor.d.ts +14 -0
  366. package/dist/tracker/sinks/vendor.js +81 -0
  367. package/dist/tracker/sinks/vendor.js.map +1 -0
  368. package/dist/tracker/transport.js +28 -0
  369. package/dist/tracker/transport.js.map +1 -0
  370. package/dist/tracker/types.d.ts +91 -0
  371. package/dist/translations/ar.js +221 -0
  372. package/dist/translations/ar.js.map +1 -0
  373. package/dist/translations/de.js +145 -1
  374. package/dist/translations/de.js.map +1 -1
  375. package/dist/translations/en.js +145 -1
  376. package/dist/translations/en.js.map +1 -1
  377. package/dist/translations/es.js +221 -0
  378. package/dist/translations/es.js.map +1 -0
  379. package/dist/translations/fr.js +221 -0
  380. package/dist/translations/fr.js.map +1 -0
  381. package/dist/translations/id.js +221 -0
  382. package/dist/translations/id.js.map +1 -0
  383. package/dist/translations/index.d.ts +10 -1
  384. package/dist/translations/index.js +19 -1
  385. package/dist/translations/index.js.map +1 -1
  386. package/dist/translations/keys.d.ts +144 -0
  387. package/dist/translations/keys.js +145 -1
  388. package/dist/translations/keys.js.map +1 -1
  389. package/dist/translations/ko.js +221 -0
  390. package/dist/translations/ko.js.map +1 -0
  391. package/dist/translations/metricKeys.js +8 -2
  392. package/dist/translations/metricKeys.js.map +1 -1
  393. package/dist/translations/pt.js +221 -0
  394. package/dist/translations/pt.js.map +1 -0
  395. package/dist/translations/ru.js +221 -0
  396. package/dist/translations/ru.js.map +1 -0
  397. package/dist/translations/server.js.map +1 -1
  398. package/dist/translations/uk.js +221 -0
  399. package/dist/translations/uk.js.map +1 -0
  400. package/dist/translations/zh.js +221 -0
  401. package/dist/translations/zh.js.map +1 -0
  402. package/dist/view/AnalyticsNavLink.d.ts +19 -0
  403. package/dist/view/AnalyticsNavLink.js +40 -0
  404. package/dist/view/AnalyticsNavLink.js.map +1 -0
  405. package/dist/view/AnalyticsView.d.ts +23 -0
  406. package/dist/view/AnalyticsView.js +45 -0
  407. package/dist/view/AnalyticsView.js.map +1 -0
  408. package/dist/view/AnalyticsViewClient.d.ts +15 -0
  409. package/dist/view/AnalyticsViewClient.js +244 -0
  410. package/dist/view/AnalyticsViewClient.js.map +1 -0
  411. package/dist/view/authRedirect.js +32 -0
  412. package/dist/view/authRedirect.js.map +1 -0
  413. package/dist/view/conversionRate.js +18 -0
  414. package/dist/view/conversionRate.js.map +1 -0
  415. package/dist/view/dayRange.js +68 -0
  416. package/dist/view/dayRange.js.map +1 -0
  417. package/dist/view/gating.d.ts +1 -0
  418. package/dist/view/gating.js +142 -0
  419. package/dist/view/gating.js.map +1 -0
  420. package/dist/view/labels.js +76 -0
  421. package/dist/view/labels.js.map +1 -0
  422. package/dist/view/registerView.js +48 -0
  423. package/dist/view/registerView.js.map +1 -0
  424. package/dist/view/sections/Breakdowns.js +198 -0
  425. package/dist/view/sections/Breakdowns.js.map +1 -0
  426. package/dist/view/sections/EmptyStates.js +92 -0
  427. package/dist/view/sections/EmptyStates.js.map +1 -0
  428. package/dist/view/sections/FilterChips.js +46 -0
  429. package/dist/view/sections/FilterChips.js.map +1 -0
  430. package/dist/view/sections/GoalsPanel.js +82 -0
  431. package/dist/view/sections/GoalsPanel.js.map +1 -0
  432. package/dist/view/sections/OverviewCards.js +65 -0
  433. package/dist/view/sections/OverviewCards.js.map +1 -0
  434. package/dist/view/sections/RealtimeStrip.js +80 -0
  435. package/dist/view/sections/RealtimeStrip.js.map +1 -0
  436. package/dist/view/sections/Toolbar.js +207 -0
  437. package/dist/view/sections/Toolbar.js.map +1 -0
  438. package/dist/view/sections/Trend.js +125 -0
  439. package/dist/view/sections/Trend.js.map +1 -0
  440. package/dist/view/sections/styles.js +76 -0
  441. package/dist/view/sections/styles.js.map +1 -0
  442. package/dist/view/state.js +211 -0
  443. package/dist/view/state.js.map +1 -0
  444. package/dist/view/useViewQueries.js +153 -0
  445. package/dist/view/useViewQueries.js.map +1 -0
  446. package/dist/view/viewProps.d.ts +40 -0
  447. package/dist/view/viewProps.js +90 -0
  448. package/dist/view/viewProps.js.map +1 -0
  449. package/dist/widgets/AnalyticsBreakdownWidget.d.ts +2 -1
  450. package/dist/widgets/AnalyticsBreakdownWidget.js +78 -11
  451. package/dist/widgets/AnalyticsBreakdownWidget.js.map +1 -1
  452. package/dist/widgets/AnalyticsGoalsWidget.d.ts +14 -0
  453. package/dist/widgets/AnalyticsGoalsWidget.js +196 -0
  454. package/dist/widgets/AnalyticsGoalsWidget.js.map +1 -0
  455. package/dist/widgets/AnalyticsMetricWidget.d.ts +2 -1
  456. package/dist/widgets/AnalyticsMetricWidget.js +63 -13
  457. package/dist/widgets/AnalyticsMetricWidget.js.map +1 -1
  458. package/dist/widgets/AnalyticsRealtimeWidget.d.ts +2 -1
  459. package/dist/widgets/AnalyticsRealtimeWidget.js +45 -23
  460. package/dist/widgets/AnalyticsRealtimeWidget.js.map +1 -1
  461. package/dist/widgets/AnalyticsTrendWidget.d.ts +2 -1
  462. package/dist/widgets/AnalyticsTrendWidget.js +79 -16
  463. package/dist/widgets/AnalyticsTrendWidget.js.map +1 -1
  464. package/dist/widgets/RealtimeCounter.d.ts +4 -0
  465. package/dist/widgets/RealtimeCounter.js +18 -4
  466. package/dist/widgets/RealtimeCounter.js.map +1 -1
  467. package/dist/widgets/WidgetViewLink.js +17 -0
  468. package/dist/widgets/WidgetViewLink.js.map +1 -0
  469. package/dist/widgets/breakdownTypes.js +38 -0
  470. package/dist/widgets/breakdownTypes.js.map +1 -1
  471. package/dist/widgets/cardChrome.js +31 -7
  472. package/dist/widgets/cardChrome.js.map +1 -1
  473. package/dist/widgets/comparison.js +15 -1
  474. package/dist/widgets/comparison.js.map +1 -1
  475. package/dist/widgets/defaults.d.ts +6 -2
  476. package/dist/widgets/defaults.js +78 -23
  477. package/dist/widgets/defaults.js.map +1 -1
  478. package/dist/widgets/filterCaption.js +27 -0
  479. package/dist/widgets/filterCaption.js.map +1 -0
  480. package/dist/widgets/filterField.d.ts +19 -0
  481. package/dist/widgets/filterField.js +75 -0
  482. package/dist/widgets/filterField.js.map +1 -0
  483. package/dist/widgets/prepareWidgetRead.d.ts +7 -0
  484. package/dist/widgets/prepareWidgetRead.js +74 -0
  485. package/dist/widgets/prepareWidgetRead.js.map +1 -0
  486. package/dist/widgets/range.js +43 -12
  487. package/dist/widgets/range.js.map +1 -1
  488. package/dist/widgets/readForWidget.d.ts +26 -3
  489. package/dist/widgets/readForWidget.js +48 -44
  490. package/dist/widgets/readForWidget.js.map +1 -1
  491. package/dist/widgets/readForWidgetBreakdown.d.ts +34 -2
  492. package/dist/widgets/readForWidgetBreakdown.js +53 -49
  493. package/dist/widgets/readForWidgetBreakdown.js.map +1 -1
  494. package/dist/widgets/readForWidgetGoals.d.ts +67 -0
  495. package/dist/widgets/readForWidgetGoals.js +140 -0
  496. package/dist/widgets/readForWidgetGoals.js.map +1 -0
  497. package/dist/widgets/readForWidgetRealtime.d.ts +8 -0
  498. package/dist/widgets/readForWidgetRealtime.js +23 -21
  499. package/dist/widgets/readForWidgetRealtime.js.map +1 -1
  500. package/dist/widgets/readForWidgetSeries.d.ts +26 -2
  501. package/dist/widgets/readForWidgetSeries.js +78 -53
  502. package/dist/widgets/readForWidgetSeries.js.map +1 -1
  503. package/dist/widgets/readMeta.js +18 -0
  504. package/dist/widgets/readMeta.js.map +1 -0
  505. package/dist/widgets/realtimePoll.js +16 -1
  506. package/dist/widgets/realtimePoll.js.map +1 -1
  507. package/dist/widgets/registerWidgets.js +76 -14
  508. package/dist/widgets/registerWidgets.js.map +1 -1
  509. package/dist/widgets/types.d.ts +15 -0
  510. package/dist/widgets/types.js +16 -2
  511. package/dist/widgets/types.js.map +1 -1
  512. package/dist/widgets/viewLink.d.ts +22 -0
  513. package/dist/widgets/viewLink.js +86 -0
  514. package/dist/widgets/viewLink.js.map +1 -0
  515. package/package.json +27 -7
  516. package/dist/native/rollups/applyDistinctDeltas.js +0 -9
  517. package/dist/native/rollups/applyDistinctDeltas.js.map +0 -1
  518. package/dist/native/rollups/bumpRollup.js +0 -68
  519. package/dist/native/rollups/bumpRollup.js.map +0 -1
  520. package/dist/native/rollups/insertIfNew.js +0 -19
  521. package/dist/native/rollups/insertIfNew.js.map +0 -1
@@ -1,27 +1,58 @@
1
+ import { zonedCalendarDay } from "../timeframe/tz.js";
2
+ import { DATE_ONLY, parseDayOrInstant } from "../query/dates.js";
1
3
  //#region src/widgets/range.ts
4
+ const NOON_MS = 12 * 36e5;
2
5
  /**
3
- * Resolve a widget's explicit custom range to a concrete DateRange, or undefined when
4
- * the widget is on a relative preset, the custom range is incomplete, or either bound
5
- * is an unparseable date (a corrupt or hand-set widgetData would otherwise reach the
6
- * cache key and throw on `toISOString`).
6
+ * The calendar day a stored bound names. The `dayOnly` picker stores the picked day at the
7
+ * admin browser's local midnight, so the instant lands on that day or the one before it in
8
+ * UTC depending on the browser's offset; a 12-hour shift recovers the picked day for every
9
+ * offset in (-12, +12]. Zones at +12:45 and beyond (Chatham in DST, Kiritimati) recover the
10
+ * day before, and the uninhabited UTC-12 the day after.
7
11
  */
8
- const resolveCustomRange = (timeframe, range) => {
12
+ const pickedDay = (raw) => {
13
+ if (DATE_ONLY.test(raw)) return raw;
14
+ const instant = new Date(raw);
15
+ if (Number.isNaN(instant.getTime())) return null;
16
+ return zonedCalendarDay(new Date(instant.getTime() + NOON_MS), "UTC");
17
+ };
18
+ /**
19
+ * Resolve a widget's explicit custom range to a concrete DateRange, or undefined when the
20
+ * widget is on a relative preset, the custom range is incomplete, or either bound names no
21
+ * real day (a corrupt or hand-set widgetData would otherwise reach the cache key and throw
22
+ * on `toISOString`). The two picked days are read inclusively in `timezone`, the reporting
23
+ * timezone the read resolves in: `from` at the first instant of its day, `to` at the last.
24
+ */
25
+ const resolveCustomRange = (timeframe, range, timezone) => {
9
26
  if (timeframe !== "custom" || !range?.from || !range?.to) return;
10
- const start = new Date(range.from);
11
- const end = new Date(range.to);
12
- if (Number.isNaN(start.getTime()) || Number.isNaN(end.getTime())) return;
27
+ const fromDay = pickedDay(range.from);
28
+ const toDay = pickedDay(range.to);
29
+ if (!fromDay || !toDay) return;
30
+ const start = parseDayOrInstant(fromDay, {
31
+ timezone,
32
+ edge: "start"
33
+ });
34
+ const end = parseDayOrInstant(toDay, {
35
+ timezone,
36
+ edge: "end"
37
+ });
38
+ if (!start || !end) return;
13
39
  return {
14
40
  start,
15
41
  end
16
42
  };
17
43
  };
18
- const formatDay = (d, locale) => d.toLocaleDateString(locale, {
44
+ const formatDay = (d, locale, timeZone) => d.toLocaleDateString(locale, {
19
45
  month: "short",
20
46
  day: "numeric",
21
- year: "numeric"
47
+ year: "numeric",
48
+ timeZone
22
49
  });
23
- /** Server-side caption for a custom range, e.g. "Jun 1, 2026 - Jun 23, 2026". */
24
- const formatRangeCaption = (range, locale) => `${formatDay(range.start, locale)} - ${formatDay(range.end, locale)}`;
50
+ /**
51
+ * Server-side caption for a custom range, e.g. "Jun 1, 2026 - Jun 23, 2026". Both bounds
52
+ * render in the reporting timezone, so the caption names the days that were read rather
53
+ * than the days the server's own zone would spell them as.
54
+ */
55
+ const formatRangeCaption = (range, locale, timezone) => `${formatDay(range.start, locale, timezone)} - ${formatDay(range.end, locale, timezone)}`;
25
56
  //#endregion
26
57
  export { formatRangeCaption, resolveCustomRange };
27
58
 
@@ -1 +1 @@
1
- {"version":3,"file":"range.js","names":[],"sources":["../../src/widgets/range.ts"],"sourcesContent":["import type { DateRange } from '../core/contract'\nimport type { WidgetRange } from './types'\n\n/**\n * Resolve a widget's explicit custom range to a concrete DateRange, or undefined when\n * the widget is on a relative preset, the custom range is incomplete, or either bound\n * is an unparseable date (a corrupt or hand-set widgetData would otherwise reach the\n * cache key and throw on `toISOString`).\n */\nexport const resolveCustomRange = (\n\ttimeframe: string | undefined,\n\trange: WidgetRange | undefined\n): DateRange | undefined => {\n\tif (timeframe !== 'custom' || !range?.from || !range?.to) {\n\t\treturn undefined\n\t}\n\tconst start = new Date(range.from)\n\tconst end = new Date(range.to)\n\tif (Number.isNaN(start.getTime()) || Number.isNaN(end.getTime())) {\n\t\treturn undefined\n\t}\n\treturn { start, end }\n}\n\nconst formatDay = (d: Date, locale: string): string =>\n\td.toLocaleDateString(locale, { month: 'short', day: 'numeric', year: 'numeric' })\n\n/** Server-side caption for a custom range, e.g. \"Jun 1, 2026 - Jun 23, 2026\". */\nexport const formatRangeCaption = (range: DateRange, locale: string): string =>\n\t`${formatDay(range.start, locale)} - ${formatDay(range.end, locale)}`\n"],"mappings":";;;;;;;AASA,MAAa,sBACZ,WACA,UAC2B;CAC3B,IAAI,cAAc,YAAY,CAAC,OAAO,QAAQ,CAAC,OAAO,IACrD;CAED,MAAM,QAAQ,IAAI,KAAK,MAAM,IAAI;CACjC,MAAM,MAAM,IAAI,KAAK,MAAM,EAAE;CAC7B,IAAI,OAAO,MAAM,MAAM,QAAQ,CAAC,KAAK,OAAO,MAAM,IAAI,QAAQ,CAAC,GAC9D;CAED,OAAO;EAAE;EAAO;CAAI;AACrB;AAEA,MAAM,aAAa,GAAS,WAC3B,EAAE,mBAAmB,QAAQ;CAAE,OAAO;CAAS,KAAK;CAAW,MAAM;AAAU,CAAC;;AAGjF,MAAa,sBAAsB,OAAkB,WACpD,GAAG,UAAU,MAAM,OAAO,MAAM,EAAE,KAAK,UAAU,MAAM,KAAK,MAAM"}
1
+ {"version":3,"file":"range.js","names":[],"sources":["../../src/widgets/range.ts"],"sourcesContent":["import type { DateRange } from '../core/contract'\nimport { DATE_ONLY, parseDayOrInstant } from '../query/dates'\nimport { zonedCalendarDay } from '../timeframe/tz'\nimport type { WidgetRange } from './types'\n\nconst NOON_MS = 12 * 3_600_000\n\n/**\n * The calendar day a stored bound names. The `dayOnly` picker stores the picked day at the\n * admin browser's local midnight, so the instant lands on that day or the one before it in\n * UTC depending on the browser's offset; a 12-hour shift recovers the picked day for every\n * offset in (-12, +12]. Zones at +12:45 and beyond (Chatham in DST, Kiritimati) recover the\n * day before, and the uninhabited UTC-12 the day after.\n */\nconst pickedDay = (raw: string): string | null => {\n\tif (DATE_ONLY.test(raw)) {\n\t\treturn raw\n\t}\n\tconst instant = new Date(raw)\n\tif (Number.isNaN(instant.getTime())) {\n\t\treturn null\n\t}\n\treturn zonedCalendarDay(new Date(instant.getTime() + NOON_MS), 'UTC')\n}\n\n/**\n * Resolve a widget's explicit custom range to a concrete DateRange, or undefined when the\n * widget is on a relative preset, the custom range is incomplete, or either bound names no\n * real day (a corrupt or hand-set widgetData would otherwise reach the cache key and throw\n * on `toISOString`). The two picked days are read inclusively in `timezone`, the reporting\n * timezone the read resolves in: `from` at the first instant of its day, `to` at the last.\n */\nexport const resolveCustomRange = (\n\ttimeframe: string | undefined,\n\trange: WidgetRange | undefined,\n\ttimezone: string\n): DateRange | undefined => {\n\tif (timeframe !== 'custom' || !range?.from || !range?.to) {\n\t\treturn undefined\n\t}\n\tconst fromDay = pickedDay(range.from)\n\tconst toDay = pickedDay(range.to)\n\tif (!fromDay || !toDay) {\n\t\treturn undefined\n\t}\n\tconst start = parseDayOrInstant(fromDay, { timezone, edge: 'start' })\n\tconst end = parseDayOrInstant(toDay, { timezone, edge: 'end' })\n\tif (!start || !end) {\n\t\treturn undefined\n\t}\n\treturn { start, end }\n}\n\nconst formatDay = (d: Date, locale: string, timeZone: string): string =>\n\td.toLocaleDateString(locale, { month: 'short', day: 'numeric', year: 'numeric', timeZone })\n\n/**\n * Server-side caption for a custom range, e.g. \"Jun 1, 2026 - Jun 23, 2026\". Both bounds\n * render in the reporting timezone, so the caption names the days that were read rather\n * than the days the server's own zone would spell them as.\n */\nexport const formatRangeCaption = (range: DateRange, locale: string, timezone: string): string =>\n\t`${formatDay(range.start, locale, timezone)} - ${formatDay(range.end, locale, timezone)}`\n"],"mappings":";;;AAKA,MAAM,UAAU,KAAK;;;;;;;;AASrB,MAAM,aAAa,QAA+B;CACjD,IAAI,UAAU,KAAK,GAAG,GACrB,OAAO;CAER,MAAM,UAAU,IAAI,KAAK,GAAG;CAC5B,IAAI,OAAO,MAAM,QAAQ,QAAQ,CAAC,GACjC,OAAO;CAER,OAAO,iBAAiB,IAAI,KAAK,QAAQ,QAAQ,IAAI,OAAO,GAAG,KAAK;AACrE;;;;;;;;AASA,MAAa,sBACZ,WACA,OACA,aAC2B;CAC3B,IAAI,cAAc,YAAY,CAAC,OAAO,QAAQ,CAAC,OAAO,IACrD;CAED,MAAM,UAAU,UAAU,MAAM,IAAI;CACpC,MAAM,QAAQ,UAAU,MAAM,EAAE;CAChC,IAAI,CAAC,WAAW,CAAC,OAChB;CAED,MAAM,QAAQ,kBAAkB,SAAS;EAAE;EAAU,MAAM;CAAQ,CAAC;CACpE,MAAM,MAAM,kBAAkB,OAAO;EAAE;EAAU,MAAM;CAAM,CAAC;CAC9D,IAAI,CAAC,SAAS,CAAC,KACd;CAED,OAAO;EAAE;EAAO;CAAI;AACrB;AAEA,MAAM,aAAa,GAAS,QAAgB,aAC3C,EAAE,mBAAmB,QAAQ;CAAE,OAAO;CAAS,KAAK;CAAW,MAAM;CAAW;AAAS,CAAC;;;;;;AAO3F,MAAa,sBAAsB,OAAkB,QAAgB,aACpE,GAAG,UAAU,MAAM,OAAO,QAAQ,QAAQ,EAAE,KAAK,UAAU,MAAM,KAAK,QAAQ,QAAQ"}
@@ -1,15 +1,27 @@
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 "./prepareWidgetRead.js";
3
4
  import { PayloadRequest } from "payload";
4
5
 
5
6
  //#region src/widgets/readForWidget.d.ts
6
- type WidgetReadStatus = 'ok' | 'not-configured' | 'unavailable';
7
7
  interface WidgetReadResult {
8
8
  status: WidgetReadStatus;
9
9
  adapterId: string;
10
10
  dateRange: DateRange;
11
11
  metrics: Partial<Record<MetricKey, number>>;
12
+ /** The source that answered, absent on a read that never reached one. */
13
+ provider?: string;
12
14
  clamped?: boolean;
15
+ /** True when the engine served a stale cache entry after a failed provider read. */
16
+ stale?: boolean;
17
+ /** True when the source answered without one of the filters the read carried. */
18
+ filtersUnapplied?: boolean;
19
+ /** True when the read hit the source's event scan cap, so the numbers are a floor. */
20
+ sampled?: boolean;
21
+ /** True when the source could not read the scope's goals, so a conversions total means nothing. */
22
+ goalsUnresolved?: boolean;
23
+ /** The read asked about goals and the scope has none configured. */
24
+ noGoals?: boolean;
13
25
  /** Previous-window totals, present only when the adapter supports comparison. */
14
26
  previousMetrics?: Partial<Record<MetricKey, number>>;
15
27
  /** The previous comparable window, present only when comparison ran. */
@@ -24,8 +36,19 @@ interface ReadForWidgetArgs {
24
36
  range?: DateRange;
25
37
  /** Explicit scope override; omitted resolves via the plugin's scopeResolver. */
26
38
  scope?: string | null;
39
+ /**
40
+ * Reporting timezone the caller already resolved, reused rather than resolved again so
41
+ * a caller-supplied `range` is read in the very timezone it was interpreted in.
42
+ */
43
+ timezone?: string;
44
+ filters?: AnalyticsFilter[];
45
+ /**
46
+ * Read the previous window too, where the install and the source both allow it. Defaults
47
+ * to on; a caller that never renders a delta passes false to save the second read.
48
+ */
49
+ comparison?: boolean;
27
50
  }
28
51
  declare const readForWidget: (args: ReadForWidgetArgs) => Promise<WidgetReadResult>;
29
52
  //#endregion
30
- export { ReadForWidgetArgs, WidgetReadResult, WidgetReadStatus, readForWidget };
53
+ export { ReadForWidgetArgs, WidgetReadResult, readForWidget };
31
54
  //# sourceMappingURL=readForWidget.d.ts.map
@@ -1,67 +1,71 @@
1
- import { satisfiesCapabilities } from "../core/capabilities.js";
2
- import { getRuntime, resolveTimezoneFor } from "../plugin/runtime.js";
3
- import { resolveReadContext } from "../core/scopedRead.js";
4
- import { resolveTimeframe } from "../timeframe/presets.js";
5
- import { previousWindow } from "./comparison.js";
1
+ import { comparisonOf } from "../core/capabilities.js";
2
+ import { previousWindow, withinLookback } from "./comparison.js";
3
+ import { prepareWidgetRead } from "./prepareWidgetRead.js";
4
+ import { readMeta } from "./readMeta.js";
6
5
  //#region src/widgets/readForWidget.ts
7
6
  const readForWidget = async (args) => {
8
- const { req, metrics, timeframe, adapterId, now, range } = args;
7
+ const { req, metrics, timeframe, adapterId, now, range, filters } = args;
9
8
  const emptyMetrics = {};
10
- const runtime = getRuntime(req.payload);
11
- if (!runtime) return {
12
- status: "unavailable",
13
- adapterId: adapterId ?? "",
14
- dateRange: range ?? resolveTimeframe(timeframe, now),
15
- metrics: emptyMetrics
16
- };
17
- const ctx = await resolveReadContext({
18
- runtime,
9
+ const prepared = await prepareWidgetRead({
19
10
  req,
11
+ now,
12
+ timeframe,
20
13
  adapterId,
21
- scope: args.scope
14
+ scope: args.scope,
15
+ timezone: args.timezone,
16
+ range,
17
+ filters,
18
+ requires: { metrics },
19
+ goalRead: () => ({ metrics })
22
20
  });
23
- if (!ctx.ok) return {
24
- status: "unavailable",
25
- adapterId: adapterId ?? "",
26
- dateRange: range ?? resolveTimeframe(timeframe, now),
21
+ if (!prepared.ok) return {
22
+ status: prepared.status,
23
+ adapterId: prepared.adapterId,
24
+ dateRange: prepared.dateRange,
27
25
  metrics: emptyMetrics
28
26
  };
29
- const tz = await resolveTimezoneFor(runtime, req, ctx.scope);
30
- const dateRange = range ?? resolveTimeframe(timeframe, now, tz);
27
+ const { runtime, adapter, tz, dateRange } = prepared;
31
28
  const base = {
32
29
  dateRange,
33
30
  metrics: emptyMetrics
34
31
  };
35
- const adapter = ctx.adapter;
36
- if (!adapter.isConfigured()) return {
37
- status: "not-configured",
38
- adapterId: adapter.id,
39
- ...base
40
- };
41
- if (!satisfiesCapabilities(adapter.capabilities, { metrics })) return {
42
- status: "unavailable",
43
- adapterId: adapter.id,
44
- ...base
45
- };
46
- const comparisonRange = runtime.comparison && adapter.capabilities.comparison ? previousWindow(dateRange, tz) ?? void 0 : void 0;
47
- const [result, previous] = await Promise.all([runtime.engine.read(adapter, {
32
+ const previousRange = args.comparison !== false && runtime.comparison && comparisonOf(adapter.capabilities) ? previousWindow(dateRange, tz) : null;
33
+ const comparisonRange = previousRange && withinLookback(previousRange, adapter.capabilities.maxLookbackDays, {
34
+ tz,
35
+ now
36
+ }) ? previousRange : void 0;
37
+ const readBase = {
48
38
  metrics,
49
- dateRange,
39
+ filters,
50
40
  timezone: tz,
51
- scope: ctx.queryScope
52
- }), comparisonRange ? runtime.engine.read(adapter, {
53
- metrics,
54
- dateRange: comparisonRange,
55
- timezone: tz,
56
- scope: ctx.queryScope
57
- }) : void 0]);
41
+ scope: prepared.queryScope,
42
+ ...prepared.goalSlugs === void 0 ? {} : { goalSlugs: prepared.goalSlugs }
43
+ };
44
+ let result;
45
+ let previous;
46
+ try {
47
+ [result, previous] = await Promise.all([runtime.engine.read(adapter, {
48
+ ...readBase,
49
+ dateRange
50
+ }), comparisonRange ? runtime.engine.read(adapter, {
51
+ ...readBase,
52
+ dateRange: comparisonRange
53
+ }) : void 0]);
54
+ } catch {
55
+ return {
56
+ status: "unavailable",
57
+ adapterId: adapter.id,
58
+ ...base
59
+ };
60
+ }
58
61
  const previousMetrics = previous ? previous.totals ?? {} : void 0;
59
62
  return {
60
63
  status: "ok",
61
64
  adapterId: adapter.id,
62
65
  dateRange,
63
66
  metrics: result.totals ?? {},
64
- clamped: result.meta.clamped ?? false,
67
+ ...readMeta(result),
68
+ noGoals: Array.isArray(prepared.goalSlugs) && prepared.goalSlugs.length === 0,
65
69
  previousMetrics,
66
70
  comparisonRange
67
71
  };
@@ -1 +1 @@
1
- {"version":3,"file":"readForWidget.js","names":[],"sources":["../../src/widgets/readForWidget.ts"],"sourcesContent":["import type { PayloadRequest } from 'payload'\nimport { satisfiesCapabilities } from '../core/capabilities'\nimport type { AnalyticsAdapter, DateRange, MetricKey } from '../core/contract'\nimport { resolveReadContext } from '../core/scopedRead'\nimport { getRuntime, resolveTimezoneFor } from '../plugin/runtime'\nimport { resolveTimeframe, type TimeframePreset } from '../timeframe/presets'\nimport { previousWindow } from './comparison'\n\nexport type WidgetReadStatus = 'ok' | 'not-configured' | 'unavailable'\n\nexport interface WidgetReadResult {\n\tstatus: WidgetReadStatus\n\tadapterId: string\n\tdateRange: DateRange\n\tmetrics: Partial<Record<MetricKey, number>>\n\tclamped?: boolean\n\t/** Previous-window totals, present only when the adapter supports comparison. */\n\tpreviousMetrics?: Partial<Record<MetricKey, number>>\n\t/** The previous comparable window, present only when comparison ran. */\n\tcomparisonRange?: DateRange\n}\n\nexport interface ReadForWidgetArgs {\n\treq: PayloadRequest\n\tmetrics: 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\nexport const readForWidget = async (args: ReadForWidgetArgs): Promise<WidgetReadResult> => {\n\tconst { req, metrics, timeframe, adapterId, now, range } = args\n\tconst emptyMetrics = {} as Partial<Record<MetricKey, number>>\n\n\tconst runtime = getRuntime(req.payload)\n\tif (!runtime) {\n\t\treturn {\n\t\t\tstatus: 'unavailable',\n\t\t\tadapterId: adapterId ?? '',\n\t\t\tdateRange: range ?? resolveTimeframe(timeframe, now),\n\t\t\tmetrics: emptyMetrics,\n\t\t}\n\t}\n\tconst ctx = await resolveReadContext({ runtime, req, adapterId, scope: args.scope })\n\tif (!ctx.ok) {\n\t\treturn {\n\t\t\tstatus: 'unavailable',\n\t\t\tadapterId: adapterId ?? '',\n\t\t\tdateRange: range ?? resolveTimeframe(timeframe, now),\n\t\t\tmetrics: emptyMetrics,\n\t\t}\n\t}\n\tconst tz = await resolveTimezoneFor(runtime, req, ctx.scope)\n\tconst dateRange = range ?? resolveTimeframe(timeframe, now, tz)\n\tconst base = { dateRange, metrics: emptyMetrics }\n\tconst adapter: AnalyticsAdapter = ctx.adapter\n\tif (!adapter.isConfigured()) {\n\t\treturn { status: 'not-configured', adapterId: adapter.id, ...base }\n\t}\n\tif (!satisfiesCapabilities(adapter.capabilities, { metrics })) {\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, { metrics, dateRange, timezone: tz, scope: ctx.queryScope }),\n\t\tcomparisonRange\n\t\t\t? runtime.engine.read(adapter, {\n\t\t\t\t\tmetrics,\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 previousMetrics = previous ? (previous.totals ?? {}) : undefined\n\treturn {\n\t\tstatus: 'ok',\n\t\tadapterId: adapter.id,\n\t\tdateRange,\n\t\tmetrics: result.totals ?? {},\n\t\tclamped: result.meta.clamped ?? false,\n\t\tpreviousMetrics,\n\t\tcomparisonRange,\n\t}\n}\n"],"mappings":";;;;;;AAiCA,MAAa,gBAAgB,OAAO,SAAuD;CAC1F,MAAM,EAAE,KAAK,SAAS,WAAW,WAAW,KAAK,UAAU;CAC3D,MAAM,eAAe,CAAC;CAEtB,MAAM,UAAU,WAAW,IAAI,OAAO;CACtC,IAAI,CAAC,SACJ,OAAO;EACN,QAAQ;EACR,WAAW,aAAa;EACxB,WAAW,SAAS,iBAAiB,WAAW,GAAG;EACnD,SAAS;CACV;CAED,MAAM,MAAM,MAAM,mBAAmB;EAAE;EAAS;EAAK;EAAW,OAAO,KAAK;CAAM,CAAC;CACnF,IAAI,CAAC,IAAI,IACR,OAAO;EACN,QAAQ;EACR,WAAW,aAAa;EACxB,WAAW,SAAS,iBAAiB,WAAW,GAAG;EACnD,SAAS;CACV;CAED,MAAM,KAAK,MAAM,mBAAmB,SAAS,KAAK,IAAI,KAAK;CAC3D,MAAM,YAAY,SAAS,iBAAiB,WAAW,KAAK,EAAE;CAC9D,MAAM,OAAO;EAAE;EAAW,SAAS;CAAa;CAChD,MAAM,UAA4B,IAAI;CACtC,IAAI,CAAC,QAAQ,aAAa,GACzB,OAAO;EAAE,QAAQ;EAAkB,WAAW,QAAQ;EAAI,GAAG;CAAK;CAEnE,IAAI,CAAC,sBAAsB,QAAQ,cAAc,EAAE,QAAQ,CAAC,GAC3D,OAAO;EAAE,QAAQ;EAAe,WAAW,QAAQ;EAAI,GAAG;CAAK;CAEhE,MAAM,kBACL,QAAQ,cAAc,QAAQ,aAAa,aACvC,eAAe,WAAW,EAAE,KAAK,KAAA,IAClC,KAAA;CACJ,MAAM,CAAC,QAAQ,YAAY,MAAM,QAAQ,IAAI,CAC5C,QAAQ,OAAO,KAAK,SAAS;EAAE;EAAS;EAAW,UAAU;EAAI,OAAO,IAAI;CAAW,CAAC,GACxF,kBACG,QAAQ,OAAO,KAAK,SAAS;EAC7B;EACA,WAAW;EACX,UAAU;EACV,OAAO,IAAI;CACZ,CAAC,IACA,KAAA,CACJ,CAAC;CACD,MAAM,kBAAkB,WAAY,SAAS,UAAU,CAAC,IAAK,KAAA;CAC7D,OAAO;EACN,QAAQ;EACR,WAAW,QAAQ;EACnB;EACA,SAAS,OAAO,UAAU,CAAC;EAC3B,SAAS,OAAO,KAAK,WAAW;EAChC;EACA;CACD;AACD"}
1
+ {"version":3,"file":"readForWidget.js","names":[],"sources":["../../src/widgets/readForWidget.ts"],"sourcesContent":["import type { PayloadRequest } from 'payload'\nimport { comparisonOf } from '../core/capabilities'\nimport type { AnalyticsFilter, AnalyticsResult, DateRange, MetricKey } from '../core/contract'\nimport type { TimeframePreset } from '../timeframe/presets'\nimport { previousWindow, withinLookback } from './comparison'\nimport { prepareWidgetRead, type WidgetReadStatus } from './prepareWidgetRead'\nimport { readMeta } from './readMeta'\n\nexport type { WidgetReadStatus } from './prepareWidgetRead'\n\nexport interface WidgetReadResult {\n\tstatus: WidgetReadStatus\n\tadapterId: string\n\tdateRange: DateRange\n\tmetrics: Partial<Record<MetricKey, 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 total means nothing. */\n\tgoalsUnresolved?: boolean\n\t/** The read asked about goals and the scope has none configured. */\n\tnoGoals?: boolean\n\t/** Previous-window totals, present only when the adapter supports comparison. */\n\tpreviousMetrics?: Partial<Record<MetricKey, number>>\n\t/** The previous comparable window, present only when comparison ran. */\n\tcomparisonRange?: DateRange\n}\n\nexport interface ReadForWidgetArgs {\n\treq: PayloadRequest\n\tmetrics: 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/**\n\t * Read the previous window too, where the install and the source both allow it. Defaults\n\t * to on; a caller that never renders a delta passes false to save the second read.\n\t */\n\tcomparison?: boolean\n}\n\nexport const readForWidget = async (args: ReadForWidgetArgs): Promise<WidgetReadResult> => {\n\tconst { req, metrics, timeframe, adapterId, now, range, filters } = args\n\tconst emptyMetrics = {} as Partial<Record<MetricKey, number>>\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 },\n\t\tgoalRead: () => ({ metrics }),\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\tmetrics: emptyMetrics,\n\t\t}\n\t}\n\tconst { runtime, adapter, tz, dateRange } = prepared\n\tconst base = { dateRange, metrics: emptyMetrics }\n\n\tconst previousRange =\n\t\targs.comparison !== false && 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\tconst readBase = {\n\t\tmetrics,\n\t\tfilters,\n\t\ttimezone: tz,\n\t\tscope: prepared.queryScope,\n\t\t...(prepared.goalSlugs === undefined ? {} : { goalSlugs: prepared.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 }),\n\t\t\tcomparisonRange\n\t\t\t\t? runtime.engine.read(adapter, { ...readBase, dateRange: comparisonRange })\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 previousMetrics = previous ? (previous.totals ?? {}) : undefined\n\treturn {\n\t\tstatus: 'ok',\n\t\tadapterId: adapter.id,\n\t\tdateRange,\n\t\tmetrics: result.totals ?? {},\n\t\t...readMeta(result),\n\t\tnoGoals: Array.isArray(prepared.goalSlugs) && prepared.goalSlugs.length === 0,\n\t\tpreviousMetrics,\n\t\tcomparisonRange,\n\t}\n}\n"],"mappings":";;;;;AAwDA,MAAa,gBAAgB,OAAO,SAAuD;CAC1F,MAAM,EAAE,KAAK,SAAS,WAAW,WAAW,KAAK,OAAO,YAAY;CACpE,MAAM,eAAe,CAAC;CAEtB,MAAM,WAAW,MAAM,kBAAkB;EACxC;EACA;EACA;EACA;EACA,OAAO,KAAK;EACZ,UAAU,KAAK;EACf;EACA;EACA,UAAU,EAAE,QAAQ;EACpB,iBAAiB,EAAE,QAAQ;CAC5B,CAAC;CACD,IAAI,CAAC,SAAS,IACb,OAAO;EACN,QAAQ,SAAS;EACjB,WAAW,SAAS;EACpB,WAAW,SAAS;EACpB,SAAS;CACV;CAED,MAAM,EAAE,SAAS,SAAS,IAAI,cAAc;CAC5C,MAAM,OAAO;EAAE;EAAW,SAAS;CAAa;CAEhD,MAAM,gBACL,KAAK,eAAe,SAAS,QAAQ,cAAc,aAAa,QAAQ,YAAY,IACjF,eAAe,WAAW,EAAE,IAC5B;CACJ,MAAM,kBACL,iBACA,eAAe,eAAe,QAAQ,aAAa,iBAAiB;EAAE;EAAI;CAAI,CAAC,IAC5E,gBACA,KAAA;CACJ,MAAM,WAAW;EAChB;EACA;EACA,UAAU;EACV,OAAO,SAAS;EAChB,GAAI,SAAS,cAAc,KAAA,IAAY,CAAC,IAAI,EAAE,WAAW,SAAS,UAAU;CAC7E;CACA,IAAI;CACJ,IAAI;CACJ,IAAI;EACF,CAAC,QAAQ,YAAY,MAAM,QAAQ,IAAI,CACvC,QAAQ,OAAO,KAAK,SAAS;GAAE,GAAG;GAAU;EAAU,CAAC,GACvD,kBACG,QAAQ,OAAO,KAAK,SAAS;GAAE,GAAG;GAAU,WAAW;EAAgB,CAAC,IACxE,KAAA,CACJ,CAAC;CACF,QAAQ;EAGP,OAAO;GAAE,QAAQ;GAAe,WAAW,QAAQ;GAAI,GAAG;EAAK;CAChE;CACA,MAAM,kBAAkB,WAAY,SAAS,UAAU,CAAC,IAAK,KAAA;CAC7D,OAAO;EACN,QAAQ;EACR,WAAW,QAAQ;EACnB;EACA,SAAS,OAAO,UAAU,CAAC;EAC3B,GAAG,SAAS,MAAM;EAClB,SAAS,MAAM,QAAQ,SAAS,SAAS,KAAK,SAAS,UAAU,WAAW;EAC5E;EACA;CACD;AACD"}
@@ -1,19 +1,33 @@
1
- import { DateRange, DimensionKey, MetricKey } from "../core/contract.js";
1
+ import { AnalyticsFilter, DateRange, DimensionKey, 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/readForWidgetBreakdown.d.ts
7
7
  interface BreakdownRow {
8
8
  label: string;
9
9
  value: number;
10
+ /** Every metric the read asked for, present only when `extraMetrics` asked for more. */
11
+ metrics?: Partial<Record<MetricKey, number>>;
10
12
  }
11
13
  interface WidgetBreakdownResult {
12
14
  status: WidgetReadStatus;
13
15
  adapterId: string;
14
16
  dateRange: DateRange;
15
17
  rows: BreakdownRow[];
18
+ /** The source that answered, absent on a read that never reached one. */
19
+ provider?: string;
16
20
  clamped?: boolean;
21
+ /** True when the engine served a stale cache entry after a failed provider read. */
22
+ stale?: boolean;
23
+ /** True when the source answered without one of the filters the read carried. */
24
+ filtersUnapplied?: boolean;
25
+ /** True when the read hit the source's event scan cap, so the numbers are a floor. */
26
+ sampled?: boolean;
27
+ /** True when the source could not read the scope's goals; the rows say nothing about them. */
28
+ goalsUnresolved?: boolean;
29
+ /** True when the read asked about goals and the scope configures none: an empty table. */
30
+ noGoals?: boolean;
17
31
  }
18
32
  interface ReadForWidgetBreakdownArgs {
19
33
  req: PayloadRequest;
@@ -26,6 +40,24 @@ interface ReadForWidgetBreakdownArgs {
26
40
  range?: DateRange;
27
41
  /** Explicit scope override; omitted resolves via the plugin's scopeResolver. */
28
42
  scope?: string | null;
43
+ /**
44
+ * Reporting timezone the caller already resolved, reused rather than resolved again so
45
+ * a caller-supplied `range` is read in the very timezone it was interpreted in.
46
+ */
47
+ timezone?: string;
48
+ filters?: AnalyticsFilter[];
49
+ /**
50
+ * Further metrics to read alongside the ranked one, narrowed to what the source serves
51
+ * so an unsupported one never turns the whole read unavailable. They reach each row's
52
+ * `metrics`; ranking and status still follow `metric` alone.
53
+ */
54
+ extraMetrics?: MetricKey[];
55
+ /**
56
+ * The scope's goal slugs, for a `goal` or `conversions` read, or `'unresolved'` when the
57
+ * caller's own resolver failed. Resolved here when omitted, so a caller that already
58
+ * resolved them (the goals table) does not resolve them twice.
59
+ */
60
+ goalSlugs?: string[] | 'unresolved';
29
61
  }
30
62
  /**
31
63
  * Site-wide ranked breakdown of one metric by one dimension, read through the engine.
@@ -1,7 +1,5 @@
1
- import { satisfiesCapabilities } from "../core/capabilities.js";
2
- import { getRuntime, resolveTimezoneFor } from "../plugin/runtime.js";
3
- import { resolveReadContext } from "../core/scopedRead.js";
4
- import { resolveTimeframe } from "../timeframe/presets.js";
1
+ import { prepareWidgetRead } from "./prepareWidgetRead.js";
2
+ import { readMeta } from "./readMeta.js";
5
3
  //#region src/widgets/readForWidgetBreakdown.ts
6
4
  /**
7
5
  * Site-wide ranked breakdown of one metric by one dimension, read through the engine.
@@ -9,69 +7,75 @@ import { resolveTimeframe } from "../timeframe/presets.js";
9
7
  * `{ label, value }` pair the bar list renders. The adapter owns sorting and limiting.
10
8
  */
11
9
  const readForWidgetBreakdown = async (args) => {
12
- const { req, metric, dimension, timeframe, limit, adapterId, now, range } = args;
10
+ const { req, metric, dimension, timeframe, limit, adapterId, now, range, filters } = args;
13
11
  const emptyRows = [];
14
- const runtime = getRuntime(req.payload);
15
- if (!runtime) return {
16
- status: "unavailable",
17
- adapterId: adapterId ?? "",
18
- dateRange: range ?? resolveTimeframe(timeframe, now),
19
- rows: emptyRows
20
- };
21
- const ctx = await resolveReadContext({
22
- runtime,
12
+ const metricsFor = (adapter) => [metric, ...(args.extraMetrics ?? []).filter((m) => m !== metric && adapter.capabilities.metrics.has(m))];
13
+ const prepared = await prepareWidgetRead({
23
14
  req,
15
+ now,
16
+ timeframe,
24
17
  adapterId,
25
- scope: args.scope
18
+ scope: args.scope,
19
+ timezone: args.timezone,
20
+ range,
21
+ filters,
22
+ requires: {
23
+ metrics: [metric],
24
+ dimensions: [dimension]
25
+ },
26
+ goalRead: (adapter) => ({
27
+ metrics: metricsFor(adapter),
28
+ dimensions: [dimension]
29
+ }),
30
+ goalSlugs: args.goalSlugs
26
31
  });
27
- if (!ctx.ok) return {
28
- status: "unavailable",
29
- adapterId: adapterId ?? "",
30
- dateRange: range ?? resolveTimeframe(timeframe, now),
32
+ if (!prepared.ok) return {
33
+ status: prepared.status,
34
+ adapterId: prepared.adapterId,
35
+ dateRange: prepared.dateRange,
31
36
  rows: emptyRows
32
37
  };
33
- const tz = await resolveTimezoneFor(runtime, req, ctx.scope);
34
- const dateRange = range ?? resolveTimeframe(timeframe, now, tz);
38
+ const { runtime, adapter, tz, dateRange, goalSlugs } = prepared;
35
39
  const base = {
36
40
  dateRange,
37
41
  rows: emptyRows
38
42
  };
39
- const adapter = ctx.adapter;
40
- if (!adapter.isConfigured()) return {
41
- status: "not-configured",
42
- adapterId: adapter.id,
43
- ...base
44
- };
45
- if (!satisfiesCapabilities(adapter.capabilities, {
46
- metrics: [metric],
47
- dimensions: [dimension]
48
- })) return {
49
- status: "unavailable",
50
- adapterId: adapter.id,
51
- ...base
52
- };
53
- const result = await runtime.engine.read(adapter, {
54
- metrics: [metric],
55
- dimensions: [dimension],
56
- dateRange,
57
- limit,
58
- order: {
59
- metric,
60
- direction: "desc"
61
- },
62
- timezone: tz,
63
- scope: ctx.queryScope
64
- });
43
+ const metrics = metricsFor(adapter);
44
+ let result;
45
+ try {
46
+ result = await runtime.engine.read(adapter, {
47
+ metrics,
48
+ dimensions: [dimension],
49
+ dateRange,
50
+ limit,
51
+ order: {
52
+ metric,
53
+ direction: "desc"
54
+ },
55
+ filters,
56
+ timezone: tz,
57
+ scope: prepared.queryScope,
58
+ ...goalSlugs === void 0 ? {} : { goalSlugs }
59
+ });
60
+ } catch {
61
+ return {
62
+ status: "unavailable",
63
+ adapterId: adapter.id,
64
+ ...base
65
+ };
66
+ }
65
67
  const rows = result.rows.map((row) => ({
66
68
  label: row.dimensions?.[dimension] ?? "(none)",
67
- value: row.metrics[metric] ?? 0
69
+ value: row.metrics[metric] ?? 0,
70
+ ...metrics.length > 1 ? { metrics: row.metrics } : {}
68
71
  }));
69
72
  return {
70
73
  status: "ok",
71
74
  adapterId: adapter.id,
72
75
  dateRange,
73
76
  rows,
74
- clamped: result.meta.clamped ?? false
77
+ ...readMeta(result),
78
+ noGoals: Array.isArray(goalSlugs) && goalSlugs.length === 0
75
79
  };
76
80
  };
77
81
  //#endregion
@@ -1 +1 @@
1
- {"version":3,"file":"readForWidgetBreakdown.js","names":[],"sources":["../../src/widgets/readForWidgetBreakdown.ts"],"sourcesContent":["import type { PayloadRequest } from 'payload'\nimport { satisfiesCapabilities } from '../core/capabilities'\nimport type { AnalyticsAdapter, DateRange, DimensionKey, MetricKey } from '../core/contract'\nimport { resolveReadContext } from '../core/scopedRead'\nimport { getRuntime, resolveTimezoneFor } from '../plugin/runtime'\nimport { resolveTimeframe, type TimeframePreset } from '../timeframe/presets'\nimport type { WidgetReadStatus } from './readForWidget'\n\nexport interface BreakdownRow {\n\tlabel: string\n\tvalue: number\n}\n\nexport interface WidgetBreakdownResult {\n\tstatus: WidgetReadStatus\n\tadapterId: string\n\tdateRange: DateRange\n\trows: BreakdownRow[]\n\tclamped?: boolean\n}\n\nexport interface ReadForWidgetBreakdownArgs {\n\treq: PayloadRequest\n\tmetric: MetricKey\n\tdimension: DimensionKey\n\ttimeframe: TimeframePreset\n\tlimit: number\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\n/**\n * Site-wide ranked breakdown of one metric by one dimension, read through the engine.\n * Mirrors `readForWidget` but gates on the dimension too and maps each result row to a\n * `{ label, value }` pair the bar list renders. The adapter owns sorting and limiting.\n */\nexport const readForWidgetBreakdown = async (\n\targs: ReadForWidgetBreakdownArgs\n): Promise<WidgetBreakdownResult> => {\n\tconst { req, metric, dimension, timeframe, limit, adapterId, now, range } = args\n\tconst emptyRows = [] as BreakdownRow[]\n\n\tconst runtime = getRuntime(req.payload)\n\tif (!runtime) {\n\t\treturn {\n\t\t\tstatus: 'unavailable',\n\t\t\tadapterId: adapterId ?? '',\n\t\t\tdateRange: range ?? resolveTimeframe(timeframe, now),\n\t\t\trows: emptyRows,\n\t\t}\n\t}\n\tconst ctx = await resolveReadContext({ runtime, req, adapterId, scope: args.scope })\n\tif (!ctx.ok) {\n\t\treturn {\n\t\t\tstatus: 'unavailable',\n\t\t\tadapterId: adapterId ?? '',\n\t\t\tdateRange: range ?? resolveTimeframe(timeframe, now),\n\t\t\trows: emptyRows,\n\t\t}\n\t}\n\tconst tz = await resolveTimezoneFor(runtime, req, ctx.scope)\n\tconst dateRange = range ?? resolveTimeframe(timeframe, now, tz)\n\tconst base = { dateRange, rows: emptyRows }\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], dimensions: [dimension] })\n\t) {\n\t\treturn { status: 'unavailable', adapterId: adapter.id, ...base }\n\t}\n\tconst result = await runtime.engine.read(adapter, {\n\t\tmetrics: [metric],\n\t\tdimensions: [dimension],\n\t\tdateRange,\n\t\tlimit,\n\t\torder: { metric, direction: 'desc' },\n\t\ttimezone: tz,\n\t\tscope: ctx.queryScope,\n\t})\n\tconst rows = result.rows.map((row) => ({\n\t\tlabel: row.dimensions?.[dimension] ?? '(none)',\n\t\tvalue: row.metrics[metric] ?? 0,\n\t}))\n\treturn {\n\t\tstatus: 'ok',\n\t\tadapterId: adapter.id,\n\t\tdateRange,\n\t\trows,\n\t\tclamped: result.meta.clamped ?? false,\n\t}\n}\n"],"mappings":";;;;;;;;;;AAuCA,MAAa,yBAAyB,OACrC,SACoC;CACpC,MAAM,EAAE,KAAK,QAAQ,WAAW,WAAW,OAAO,WAAW,KAAK,UAAU;CAC5E,MAAM,YAAY,CAAC;CAEnB,MAAM,UAAU,WAAW,IAAI,OAAO;CACtC,IAAI,CAAC,SACJ,OAAO;EACN,QAAQ;EACR,WAAW,aAAa;EACxB,WAAW,SAAS,iBAAiB,WAAW,GAAG;EACnD,MAAM;CACP;CAED,MAAM,MAAM,MAAM,mBAAmB;EAAE;EAAS;EAAK;EAAW,OAAO,KAAK;CAAM,CAAC;CACnF,IAAI,CAAC,IAAI,IACR,OAAO;EACN,QAAQ;EACR,WAAW,aAAa;EACxB,WAAW,SAAS,iBAAiB,WAAW,GAAG;EACnD,MAAM;CACP;CAED,MAAM,KAAK,MAAM,mBAAmB,SAAS,KAAK,IAAI,KAAK;CAC3D,MAAM,YAAY,SAAS,iBAAiB,WAAW,KAAK,EAAE;CAC9D,MAAM,OAAO;EAAE;EAAW,MAAM;CAAU;CAC1C,MAAM,UAA4B,IAAI;CACtC,IAAI,CAAC,QAAQ,aAAa,GACzB,OAAO;EAAE,QAAQ;EAAkB,WAAW,QAAQ;EAAI,GAAG;CAAK;CAEnE,IACC,CAAC,sBAAsB,QAAQ,cAAc;EAAE,SAAS,CAAC,MAAM;EAAG,YAAY,CAAC,SAAS;CAAE,CAAC,GAE3F,OAAO;EAAE,QAAQ;EAAe,WAAW,QAAQ;EAAI,GAAG;CAAK;CAEhE,MAAM,SAAS,MAAM,QAAQ,OAAO,KAAK,SAAS;EACjD,SAAS,CAAC,MAAM;EAChB,YAAY,CAAC,SAAS;EACtB;EACA;EACA,OAAO;GAAE;GAAQ,WAAW;EAAO;EACnC,UAAU;EACV,OAAO,IAAI;CACZ,CAAC;CACD,MAAM,OAAO,OAAO,KAAK,KAAK,SAAS;EACtC,OAAO,IAAI,aAAa,cAAc;EACtC,OAAO,IAAI,QAAQ,WAAW;CAC/B,EAAE;CACF,OAAO;EACN,QAAQ;EACR,WAAW,QAAQ;EACnB;EACA;EACA,SAAS,OAAO,KAAK,WAAW;CACjC;AACD"}
1
+ {"version":3,"file":"readForWidgetBreakdown.js","names":[],"sources":["../../src/widgets/readForWidgetBreakdown.ts"],"sourcesContent":["import type { PayloadRequest } from 'payload'\nimport type {\n\tAnalyticsAdapter,\n\tAnalyticsFilter,\n\tAnalyticsResult,\n\tDateRange,\n\tDimensionKey,\n\tMetricKey,\n} from '../core/contract'\nimport type { TimeframePreset } from '../timeframe/presets'\nimport { prepareWidgetRead, type WidgetReadStatus } from './prepareWidgetRead'\nimport { readMeta } from './readMeta'\n\nexport interface BreakdownRow {\n\tlabel: string\n\tvalue: number\n\t/** Every metric the read asked for, present only when `extraMetrics` asked for more. */\n\tmetrics?: Partial<Record<MetricKey, number>>\n}\n\nexport interface WidgetBreakdownResult {\n\tstatus: WidgetReadStatus\n\tadapterId: string\n\tdateRange: DateRange\n\trows: BreakdownRow[]\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; the rows say nothing about them. */\n\tgoalsUnresolved?: boolean\n\t/** True when the read asked about goals and the scope configures none: an empty table. */\n\tnoGoals?: boolean\n}\n\nexport interface ReadForWidgetBreakdownArgs {\n\treq: PayloadRequest\n\tmetric: MetricKey\n\tdimension: DimensionKey\n\ttimeframe: TimeframePreset\n\tlimit: number\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/**\n\t * Further metrics to read alongside the ranked one, narrowed to what the source serves\n\t * so an unsupported one never turns the whole read unavailable. They reach each row's\n\t * `metrics`; ranking and status still follow `metric` alone.\n\t */\n\textraMetrics?: MetricKey[]\n\t/**\n\t * The scope's goal slugs, for a `goal` or `conversions` read, or `'unresolved'` when the\n\t * caller's own resolver failed. Resolved here when omitted, so a caller that already\n\t * resolved them (the goals table) does not resolve them twice.\n\t */\n\tgoalSlugs?: string[] | 'unresolved'\n}\n\n/**\n * Site-wide ranked breakdown of one metric by one dimension, read through the engine.\n * Mirrors `readForWidget` but gates on the dimension too and maps each result row to a\n * `{ label, value }` pair the bar list renders. The adapter owns sorting and limiting.\n */\nexport const readForWidgetBreakdown = async (\n\targs: ReadForWidgetBreakdownArgs\n): Promise<WidgetBreakdownResult> => {\n\tconst { req, metric, dimension, timeframe, limit, adapterId, now, range, filters } = args\n\tconst emptyRows = [] as BreakdownRow[]\n\n\tconst metricsFor = (adapter: AnalyticsAdapter): MetricKey[] => [\n\t\tmetric,\n\t\t...(args.extraMetrics ?? []).filter((m) => m !== metric && adapter.capabilities.metrics.has(m)),\n\t]\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], dimensions: [dimension] },\n\t\tgoalRead: (adapter) => ({ metrics: metricsFor(adapter), dimensions: [dimension] }),\n\t\tgoalSlugs: args.goalSlugs,\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\trows: emptyRows,\n\t\t}\n\t}\n\tconst { runtime, adapter, tz, dateRange, goalSlugs } = prepared\n\tconst base = { dateRange, rows: emptyRows }\n\tconst metrics = metricsFor(adapter)\n\tlet result: AnalyticsResult\n\ttry {\n\t\tresult = await runtime.engine.read(adapter, {\n\t\t\tmetrics,\n\t\t\tdimensions: [dimension],\n\t\t\tdateRange,\n\t\t\tlimit,\n\t\t\torder: { metric, direction: 'desc' },\n\t\t\tfilters,\n\t\t\ttimezone: tz,\n\t\t\tscope: prepared.queryScope,\n\t\t\t...(goalSlugs === undefined ? {} : { goalSlugs }),\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 rows = result.rows.map((row) => ({\n\t\tlabel: row.dimensions?.[dimension] ?? '(none)',\n\t\tvalue: row.metrics[metric] ?? 0,\n\t\t...(metrics.length > 1 ? { metrics: row.metrics } : {}),\n\t}))\n\treturn {\n\t\tstatus: 'ok',\n\t\tadapterId: adapter.id,\n\t\tdateRange,\n\t\trows,\n\t\t...readMeta(result),\n\t\t// The hint is set only for a read about goals, so an empty one is a scope that\n\t\t// configured none rather than a read that never asked.\n\t\tnoGoals: Array.isArray(goalSlugs) && goalSlugs.length === 0,\n\t}\n}\n"],"mappings":";;;;;;;;AA4EA,MAAa,yBAAyB,OACrC,SACoC;CACpC,MAAM,EAAE,KAAK,QAAQ,WAAW,WAAW,OAAO,WAAW,KAAK,OAAO,YAAY;CACrF,MAAM,YAAY,CAAC;CAEnB,MAAM,cAAc,YAA2C,CAC9D,QACA,IAAI,KAAK,gBAAgB,CAAC,GAAG,QAAQ,MAAM,MAAM,UAAU,QAAQ,aAAa,QAAQ,IAAI,CAAC,CAAC,CAC/F;CACA,MAAM,WAAW,MAAM,kBAAkB;EACxC;EACA;EACA;EACA;EACA,OAAO,KAAK;EACZ,UAAU,KAAK;EACf;EACA;EACA,UAAU;GAAE,SAAS,CAAC,MAAM;GAAG,YAAY,CAAC,SAAS;EAAE;EACvD,WAAW,aAAa;GAAE,SAAS,WAAW,OAAO;GAAG,YAAY,CAAC,SAAS;EAAE;EAChF,WAAW,KAAK;CACjB,CAAC;CACD,IAAI,CAAC,SAAS,IACb,OAAO;EACN,QAAQ,SAAS;EACjB,WAAW,SAAS;EACpB,WAAW,SAAS;EACpB,MAAM;CACP;CAED,MAAM,EAAE,SAAS,SAAS,IAAI,WAAW,cAAc;CACvD,MAAM,OAAO;EAAE;EAAW,MAAM;CAAU;CAC1C,MAAM,UAAU,WAAW,OAAO;CAClC,IAAI;CACJ,IAAI;EACH,SAAS,MAAM,QAAQ,OAAO,KAAK,SAAS;GAC3C;GACA,YAAY,CAAC,SAAS;GACtB;GACA;GACA,OAAO;IAAE;IAAQ,WAAW;GAAO;GACnC;GACA,UAAU;GACV,OAAO,SAAS;GAChB,GAAI,cAAc,KAAA,IAAY,CAAC,IAAI,EAAE,UAAU;EAChD,CAAC;CACF,QAAQ;EAGP,OAAO;GAAE,QAAQ;GAAe,WAAW,QAAQ;GAAI,GAAG;EAAK;CAChE;CACA,MAAM,OAAO,OAAO,KAAK,KAAK,SAAS;EACtC,OAAO,IAAI,aAAa,cAAc;EACtC,OAAO,IAAI,QAAQ,WAAW;EAC9B,GAAI,QAAQ,SAAS,IAAI,EAAE,SAAS,IAAI,QAAQ,IAAI,CAAC;CACtD,EAAE;CACF,OAAO;EACN,QAAQ;EACR,WAAW,QAAQ;EACnB;EACA;EACA,GAAG,SAAS,MAAM;EAGlB,SAAS,MAAM,QAAQ,SAAS,KAAK,UAAU,WAAW;CAC3D;AACD"}
@@ -0,0 +1,67 @@
1
+ import { DateRange } from "../core/contract.js";
2
+ import { TimeframePreset } from "../timeframe/presets.js";
3
+ import { WidgetReadStatus } from "./prepareWidgetRead.js";
4
+ import { PayloadRequest } from "payload";
5
+
6
+ //#region src/widgets/readForWidgetGoals.d.ts
7
+ interface GoalRow {
8
+ slug: string;
9
+ /** The goal's admin-facing name, or its slug when no configured goal claims it. */
10
+ name: string;
11
+ conversions: number;
12
+ revenue?: number;
13
+ /** 0..1 share of the site's visitors, absent when either side of the ratio is missing. */
14
+ rate?: number;
15
+ previousConversions?: number;
16
+ }
17
+ interface WidgetGoalsResult {
18
+ status: WidgetReadStatus;
19
+ adapterId: string;
20
+ dateRange: DateRange;
21
+ timezone: string;
22
+ rows: GoalRow[];
23
+ /** Range total the rate divides by; absent when the source does not serve visitors. */
24
+ siteVisitors?: number;
25
+ /** The source that answered, absent on a read that never reached one. */
26
+ provider?: string;
27
+ clamped?: boolean;
28
+ stale?: boolean;
29
+ /** True when the source answered without one of the filters a read carried. */
30
+ filtersUnapplied?: boolean;
31
+ /** True when a read hit the source's event scan cap, so the numbers are a floor. */
32
+ sampled?: boolean;
33
+ /** True when the source could not read the scope's goals, so the empty table means nothing. */
34
+ goalsUnresolved?: boolean;
35
+ /** True when the scope configures no goals at all, which is an empty table, not a failure. */
36
+ noGoals?: boolean;
37
+ }
38
+ interface ReadForWidgetGoalsArgs {
39
+ req: PayloadRequest;
40
+ timeframe: TimeframePreset;
41
+ limit: number;
42
+ /** Read the previous window too, when the source can compare. */
43
+ compare: boolean;
44
+ adapterId?: string;
45
+ now: Date;
46
+ range?: DateRange;
47
+ /** Explicit scope override; omitted resolves via the plugin's scopeResolver. */
48
+ scope?: string | null;
49
+ /**
50
+ * Reporting timezone the caller already resolved, reused rather than resolved again so
51
+ * a caller-supplied `range` is read in the very timezone it was interpreted in.
52
+ */
53
+ timezone?: string;
54
+ }
55
+ /**
56
+ * The goals table behind the goals widget: conversions per goal over the window, each with
57
+ * its revenue, its share of the site's visitors, and (when comparing) the same goal's
58
+ * conversions in the previous window. Rows come from one `goal` breakdown read and the site
59
+ * total from one totals read, both through the existing widget helpers so capability
60
+ * gating, scoping and caching stay in one place. Revenue and visitors ride along only where
61
+ * the source serves them; the status is the breakdown's, since a table without its rows has
62
+ * nothing to show.
63
+ */
64
+ declare const readForWidgetGoals: (args: ReadForWidgetGoalsArgs) => Promise<WidgetGoalsResult>;
65
+ //#endregion
66
+ export { GoalRow, ReadForWidgetGoalsArgs, WidgetGoalsResult, readForWidgetGoals };
67
+ //# sourceMappingURL=readForWidgetGoals.d.ts.map