@antelopejs/dms-marketing 0.4.1 → 0.5.0

package/frontend-vue/app/composables/useMarketingApi.ts

@@ -1,9 +1,9 @@
 /**
  * Frontend marketing facade.
  *
- * Single composable wrapping every /api/marketing/* fetch the module pages
- * need — the one file to update when endpoint shapes change (same swap-point
- * convention as dms-api's useApiIntrospection).
+ * The /api/marketing/* writes, and the funnel preview the builder posts its
+ * draft to. Every read goes through `useMarketingReads`. The response shapes
+ * are declared here.
  */
 
 import type {
@@ -394,24 +394,10 @@ export interface MarketingScrollDepth {
 
 // --- Facade -----------------------------------------------------------------
 
-function periodUrl(url: string, period: MarketingPeriod): string {
-  return appendPeriodToUrl(url, period) ?? url
-}
-
-/** Far above any real tenant's funnel count — the data-api list answers 10
- * rows unless told otherwise, and caps at 100 whatever is asked. */
-const FUNNEL_LIST_LIMIT = 100
-
 export function useMarketingApi() {
   const { $authFetch } = useAuthFetch()
 
   return {
-    listWebsites: () =>
-      $authFetch<MarketingWebsite[]>('/api/marketing/websites'),
-
-    getContext: () =>
-      $authFetch<MarketingContextPayload>('/api/marketing/context'),
-
     createWebsite: (input: MarketingWebsiteInput) =>
       $authFetch<MarketingWebsite>('/api/marketing/websites', {
         method: 'POST',
@@ -424,21 +410,6 @@ export function useMarketingApi() {
         body: { website },
       }),
 
-    listWebsiteCards: () =>
-      $authFetch<MarketingWebsiteCard[]>('/api/marketing/websites/summary'),
-
-    // `since` (epoch ms, server clock): only a pageview from then on counts.
-    getConnection: (website: string, since?: number) =>
-      $authFetch<MarketingConnectionStatus>(
-        `/api/marketing/websites/${encodeURIComponent(website)}/connection`,
-        { query: { since } },
-      ),
-
-    getWebsiteDeletionImpact: (website: string) =>
-      $authFetch<MarketingWebsiteDeletionImpact>(
-        `/api/marketing/websites/${encodeURIComponent(website)}/deletion`,
-      ),
-
     allowHost: (website: string, hostname: string) =>
       $authFetch<MarketingWebsite>(
         `/api/marketing/websites/${encodeURIComponent(website)}/allow-host`,
@@ -451,22 +422,6 @@ export function useMarketingApi() {
         { method: 'DELETE' },
       ),
 
-    getFunnelTemplates: (website: string, period: MarketingPeriod) =>
-      $authFetch<MarketingFunnelTemplate[]>(
-        periodUrl('/api/marketing/funnels/templates', period),
-        {
-          query: { website },
-        },
-      ),
-
-    getFunnelSuggestions: (website: string) =>
-      $authFetch<MarketingFunnelSuggestions>(
-        '/api/marketing/funnels/suggestions',
-        {
-          query: { website },
-        },
-      ),
-
     previewFunnel: (
       website: string,
       steps: MarketingFunnelStep[],
@@ -484,85 +439,17 @@ export function useMarketingApi() {
         { method: 'PUT', body: patch },
       ),
 
-    // Query strings via ofetch's `query` option — encoding is its job.
-    listPages: (
-      website: string,
-      period: MarketingPeriod,
-      search = '',
-      sort: MarketingPagesSort = 'views',
-    ) =>
-      $authFetch<MarketingPages>(
-        periodUrl('/api/marketing/stats/pages', period),
-        {
-          query: { website, search, sort },
-        },
-      ),
-
-    getHeatmap: (website: string, path: string, period: MarketingPeriod) =>
-      $authFetch<MarketingHeatmap>(
-        periodUrl('/api/marketing/stats/heatmap', period),
-        {
-          query: { website, path },
-        },
-      ),
-
-    getScrollDepth: (website: string, path: string, period: MarketingPeriod) =>
-      $authFetch<MarketingScrollDepth>(
-        periodUrl('/api/marketing/stats/scroll', period),
-        {
-          query: { website, path },
-        },
-      ),
-
-    getSnapshot: (
-      website: string,
-      path: string,
-      layout: MarketingSnapshotLayout,
-    ) =>
-      $authFetch<MarketingPageSnapshotResponse>(
-        '/api/marketing/stats/snapshot',
-        {
-          query: { website, path, layout },
-        },
-      ),
-
     // Whole click and scroll history, every period: without `path` the whole
-    // site's.
+    // site's (counted first by `useHeatmapCountRead`).
     resetHeatmap: (website: string, path?: string) =>
       $authFetch<MarketingHeatmapData>('/api/marketing/stats/heatmap', {
         method: 'DELETE',
         query: { website, path },
       }),
 
-    /** What `resetHeatmap` would delete with the same arguments. */
-    countHeatmap: (website: string, path?: string) =>
-      $authFetch<MarketingHeatmapData>('/api/marketing/stats/heatmap/count', {
-        query: { website, path },
-      }),
-
-    // Definitions CRUD over the funnels data-api routes. `is` is the DMS
-    // DataType compare mode — the data-api's own `eq` parses but matches
-    // nothing. The list defaults to 10 rows, hence the explicit limit.
-    listFunnels: (website: string) =>
-      $authFetch<{ results: MarketingFunnelListItem[]; total: number }>(
-        '/api/marketing/tables/funnels/list',
-        {
-          query: {
-            filter_websiteId: `is:${website}`,
-            limit: FUNNEL_LIST_LIMIT,
-            sortKey: 'createdAt',
-            sortDirection: 'asc',
-          },
-        },
-      ),
-
-    // One definition, as the builder edits it: no results computed.
-    getFunnel: (id: string) =>
-      $authFetch<MarketingFunnelListItem>('/api/marketing/tables/funnels/get', {
-        query: { id },
-      }),
-
-    // The insert answers the generated keys, an array — not the row.
+    // Definitions CRUD over the funnels data-api routes; the list is read by
+    // `useWebsiteFunnels`, one definition by `useFunnelRead`. The insert
+    // answers the generated keys, an array — not the row.
     createFunnel: (input: MarketingFunnelInput) =>
       $authFetch<string[]>('/api/marketing/tables/funnels/new', {
         method: 'POST',

package/frontend-vue/app/composables/useMarketingContext.ts

@@ -1,10 +1,4 @@
-import {
-  computed,
-  inject,
-  type ComputedRef,
-  type InjectionKey,
-  type Ref,
-} from 'vue'
+import { computed, inject, type ComputedRef, type InjectionKey } from 'vue'
 
 export type WebsiteState = 'live' | 'waiting' | 'paused'
 
@@ -25,8 +19,6 @@ export interface MarketingContextPayload {
 export interface MarketingContextState {
   websites: ComputedRef<ContextWebsite[]>
   selected: ComputedRef<ContextWebsite | null>
-  /** Bumped by the bar's refresh button. */
-  refreshToken: Ref<number>
   select: (id: string) => Promise<void>
   reload: () => Promise<void>
 }
@@ -48,7 +40,6 @@ function detachedContext(): MarketingContextState {
   return {
     websites: computed(() => []),
     selected: computed(() => null),
-    refreshToken: { value: 0 } as Ref<number>,
     select: async () => {},
     reload: async () => {},
   }

package/frontend-vue/app/composables/useMarketingNow.ts

@@ -0,0 +1,29 @@
+import { onBeforeUnmount, onMounted, ref, type Ref } from 'vue'
+
+const RENDERED_AT_STATE_KEY = 'marketing-rendered-at'
+
+/**
+ * The current time, in epoch ms, for what a page writes relative to it
+ * ("12 seconds ago", a site still live): the time the server rendered the
+ * page, which the browser hydrating its HTML starts from too, then the
+ * browser's clock once mounted, every `tickMs`.
+ */
+export function useMarketingNow(tickMs: number): Ref<number> {
+  const renderedAt = useDmsState<number>(
+    RENDERED_AT_STATE_KEY,
+    () => Date.now(),
+    { transfer: true },
+  )
+  const now = ref(renderedAt.value)
+  let clock: ReturnType<typeof setInterval> | null = null
+  onMounted(() => {
+    now.value = Date.now()
+    clock = setInterval(() => (now.value = Date.now()), tickMs)
+  })
+  onBeforeUnmount(() => {
+    if (clock) {
+      clearInterval(clock)
+    }
+  })
+  return now
+}

package/frontend-vue/app/composables/useMarketingReads.ts

@@ -0,0 +1,314 @@
+import { computed, toValue, type MaybeRefOrGetter } from 'vue'
+import type { MarketingContextPayload } from './useMarketingContext'
+import type {
+  MarketingConnectionStatus,
+  MarketingFunnelListItem,
+  MarketingFunnelSuggestions,
+  MarketingFunnelTemplate,
+  MarketingHeatmap,
+  MarketingHeatmapData,
+  MarketingPageSnapshotResponse,
+  MarketingPages,
+  MarketingPagesSort,
+  MarketingPeriod,
+  MarketingScrollDepth,
+  MarketingSnapshotLayout,
+  MarketingWebsite,
+  MarketingWebsiteCard,
+  MarketingWebsiteDeletionImpact,
+} from './useMarketingApi'
+
+/**
+ * The module's reads, through `useApiData`. What the pages render: a server
+ * render reads it and hands it to the browser with the page, the components
+ * showing one request share it, and a newer request replaces one still in
+ * flight (the answer for a site, page or period the user left never paints
+ * over the one on screen). The page preview and the funnel builder draw in
+ * the browser only (`server: false`); a dialog or the builder reads what it
+ * shows when it asks (`ReadOnDemand`). The page's refreshes
+ * (`refreshPageBlocks()`) read every one of them again but the context
+ * bar's, which reads on its own clock. Writes go through `useMarketingApi`.
+ *
+ * A read bound to the period waits for it: the server knows it only once the
+ * browser's time zone is known, and the browser once the context bar's
+ * selector has set up. Until then nothing is read and the block shows its
+ * skeleton, on both sides.
+ */
+
+/** Far above any real tenant's funnel count (the data-api caps at 100). */
+const FUNNEL_LIST_LIMIT = 100
+
+/** `url` with the period's bounds, or nothing to read without a period. */
+function periodRead(
+  url: string,
+  period: MaybeRefOrGetter<MarketingPeriod>,
+): string | null {
+  const state = toValue(period)
+  return state ? (appendPeriodToUrl(url, state) ?? url) : null
+}
+
+/** How the context bar reads the context: on its own clock. */
+export interface ContextReadOptions {
+  /**
+   * Reads again every this many milliseconds while the caller shows the
+   * data; a ref or a getter changes it, and `0` or `null` stops it.
+   */
+  refreshInterval?: MaybeRefOrGetter<number | null | undefined>
+}
+
+/**
+ * The tenant's websites as the context bar lists them, and the saved pick:
+ * read again on the bar's own triggers (its clock, its refresh button), not
+ * with the page's blocks.
+ */
+export function useMarketingContextRead(
+  options: ContextReadOptions = {},
+): ApiDataResult<MarketingContextPayload> {
+  return useApiData<MarketingContextPayload>('/api/marketing/context', {
+    refreshOnPageRefresh: false,
+    refreshInterval: options.refreshInterval,
+  })
+}
+
+/** The Websites page's cards. */
+export function useWebsiteCards(): ApiDataResult<MarketingWebsiteCard[]> {
+  return useApiData<MarketingWebsiteCard[]>('/api/marketing/websites/summary')
+}
+
+/** The tenant's websites, with their capture options. */
+export function useWebsites(): ApiDataResult<MarketingWebsite[]> {
+  return useApiData<MarketingWebsite[]>('/api/marketing/websites')
+}
+
+/** The funnels of a website, oldest first; nothing read without one. */
+export function useWebsiteFunnels(
+  websiteId: MaybeRefOrGetter<string>,
+): ApiDataResult<MarketingFunnelListItem[]> {
+  return useApiData<MarketingFunnelListItem[]>(
+    () => (toValue(websiteId) ? '/api/marketing/tables/funnels/list' : null),
+    {
+      query: () => ({
+        filter_websiteId: `is:${toValue(websiteId)}`,
+        limit: FUNNEL_LIST_LIMIT,
+        sortKey: 'createdAt',
+        sortDirection: 'asc',
+      }),
+      transform: (value) =>
+        (value as { results: MarketingFunnelListItem[] }).results,
+    },
+  )
+}
+
+export interface PageInventoryRequest {
+  websiteId: MaybeRefOrGetter<string>
+  period: MaybeRefOrGetter<MarketingPeriod>
+  search: MaybeRefOrGetter<string>
+  sort: MaybeRefOrGetter<MarketingPagesSort>
+}
+
+/** The paths a website's visitors loaded over the period. */
+export function usePageInventory(
+  request: PageInventoryRequest,
+): ApiDataResult<MarketingPages> {
+  return useApiData<MarketingPages>(
+    () =>
+      toValue(request.websiteId)
+        ? periodRead('/api/marketing/stats/pages', request.period)
+        : null,
+    {
+      query: () => ({
+        website: toValue(request.websiteId),
+        search: toValue(request.search),
+        sort: toValue(request.sort),
+      }),
+    },
+  )
+}
+
+/** Funnels built from a website's own journeys over the period. */
+export function useFunnelTemplates(
+  websiteId: MaybeRefOrGetter<string | undefined>,
+  period: MaybeRefOrGetter<MarketingPeriod>,
+): ApiDataResult<MarketingFunnelTemplate[]> {
+  return useApiData<MarketingFunnelTemplate[]>(
+    () =>
+      toValue(websiteId)
+        ? periodRead('/api/marketing/funnels/templates', period)
+        : null,
+    { query: () => ({ website: toValue(websiteId) }) },
+  )
+}
+
+/**
+ * Whether a website's tag reached the collector: since its creation, or
+ * since `since` (epoch ms, server clock). Polled every
+ * `options.refreshInterval` while it is above 0.
+ */
+export function useWebsiteConnection(
+  websiteId: MaybeRefOrGetter<string>,
+  since: MaybeRefOrGetter<number | null>,
+  options: ContextReadOptions = {},
+): ApiDataResult<MarketingConnectionStatus> {
+  const path = computed(() => {
+    const id = toValue(websiteId)
+    return id
+      ? `/api/marketing/websites/${encodeURIComponent(id)}/connection`
+      : null
+  })
+  return useApiData<MarketingConnectionStatus>(path, {
+    query: () => ({ since: toValue(since) ?? undefined }),
+    refreshInterval: options.refreshInterval,
+  })
+}
+
+/** `url` with the period's bounds, or the routes' default without one. */
+function withPeriod(url: string, period: MarketingPeriod): string {
+  return period ? (appendPeriodToUrl(url, period) ?? url) : url
+}
+
+/** The page of a website the preview shows, over the context's period. */
+export interface PagePreviewRequest {
+  websiteId: MaybeRefOrGetter<string | undefined>
+  path: MaybeRefOrGetter<string>
+  period: MaybeRefOrGetter<MarketingPeriod>
+}
+
+function previewRead<T>(
+  url: string,
+  request: PagePreviewRequest,
+): ApiDataResult<T> {
+  return useApiData<T>(
+    () =>
+      toValue(request.websiteId) && toValue(request.path)
+        ? withPeriod(url, toValue(request.period))
+        : null,
+    {
+      query: () => ({
+        website: toValue(request.websiteId),
+        path: toValue(request.path),
+      }),
+      server: false,
+    },
+  )
+}
+
+/** The clicks of a page over the period, drawn in the browser. */
+export function usePageHeatmap(
+  request: PagePreviewRequest,
+): ApiDataResult<MarketingHeatmap> {
+  return previewRead('/api/marketing/stats/heatmap', request)
+}
+
+/** How far a page's visitors scrolled over the period, drawn in the browser. */
+export function usePageScrollDepth(
+  request: PagePreviewRequest,
+): ApiDataResult<MarketingScrollDepth> {
+  return previewRead('/api/marketing/stats/scroll', request)
+}
+
+/** The capture of a page a layout shows; nothing read while `enabled` is false. */
+export interface PageSnapshotRequest {
+  websiteId: MaybeRefOrGetter<string | undefined>
+  path: MaybeRefOrGetter<string>
+  layout: MaybeRefOrGetter<MarketingSnapshotLayout>
+  enabled: MaybeRefOrGetter<boolean>
+}
+
+/** A page's capture in a layout, drawn in the browser. */
+export function usePageSnapshot(
+  request: PageSnapshotRequest,
+): ApiDataResult<MarketingPageSnapshotResponse> {
+  return useApiData<MarketingPageSnapshotResponse>(
+    () =>
+      toValue(request.enabled) &&
+      toValue(request.websiteId) &&
+      toValue(request.path)
+        ? '/api/marketing/stats/snapshot'
+        : null,
+    {
+      query: () => ({
+        website: toValue(request.websiteId),
+        path: toValue(request.path),
+        layout: toValue(request.layout),
+      }),
+      server: false,
+    },
+  )
+}
+
+/** The pages and events a website's visitors sent, for the funnel builder. */
+export function useFunnelSuggestions(
+  websiteId: MaybeRefOrGetter<string>,
+): ApiDataResult<MarketingFunnelSuggestions> {
+  return useApiData<MarketingFunnelSuggestions>(
+    () => (toValue(websiteId) ? '/api/marketing/funnels/suggestions' : null),
+    { query: () => ({ website: toValue(websiteId) }), server: false },
+  )
+}
+
+/** The query of a read made on demand. */
+type ReadQuery = MaybeRefOrGetter<Record<string, string | undefined>>
+
+/**
+ * A read a dialog or the funnel builder makes when it asks, through
+ * `useApiData` with `immediate: false`: the call reads the current URL and
+ * resolves with its answer, or rejects with what the read failed with. The
+ * caller keeps the answer, so the page's refreshes leave it.
+ */
+export type ReadOnDemand<T> = () => Promise<T>
+
+function useReadOnDemand<T>(
+  url: MaybeRefOrGetter<string | null>,
+  query?: ReadQuery,
+): ReadOnDemand<T> {
+  const read = useApiData<T>(url, {
+    query,
+    immediate: false,
+    refreshOnPageRefresh: false,
+  })
+  return async () => {
+    await read.execute({ dedupe: 'defer' })
+    if (read.error.value) {
+      throw read.error.value
+    }
+    return read.data.value as T
+  }
+}
+
+/** What deleting a website discards, for its confirmation. */
+export function useWebsiteDeletionImpactRead(
+  websiteId: MaybeRefOrGetter<string>,
+): ReadOnDemand<MarketingWebsiteDeletionImpact> {
+  return useReadOnDemand(() => {
+    const id = toValue(websiteId)
+    return id
+      ? `/api/marketing/websites/${encodeURIComponent(id)}/deletion`
+      : null
+  })
+}
+
+/** What resetting the clicks of a page, or of the whole site, deletes. */
+export function useHeatmapCountRead(
+  websiteId: MaybeRefOrGetter<string>,
+  path: MaybeRefOrGetter<string | undefined> = undefined,
+): ReadOnDemand<MarketingHeatmapData> {
+  return useReadOnDemand(
+    () => (toValue(websiteId) ? '/api/marketing/stats/heatmap/count' : null),
+    () => ({ website: toValue(websiteId), path: toValue(path) }),
+  )
+}
+
+/** One funnel definition, as the builder edits it. */
+export function useFunnelRead(
+  funnelId: MaybeRefOrGetter<string>,
+): ReadOnDemand<MarketingFunnelListItem> {
+  return useReadOnDemand(
+    () => (toValue(funnelId) ? '/api/marketing/tables/funnels/get' : null),
+    () => ({ id: toValue(funnelId) }),
+  )
+}
+
+/** The websites and the saved pick, for the builder outside the context bar. */
+export function useContextOnDemand(): ReadOnDemand<MarketingContextPayload> {
+  return useReadOnDemand('/api/marketing/context')
+}

package/frontend-vue/app/utils/format.ts

@@ -101,10 +101,46 @@ export function formatDateRange(from: Date, to: Date, locale: string): string {
   }).formatRange(from, to)
 }
 
-export function formatShortDate(at: number | Date, locale: string): string {
+/**
+ * When the statistics' day (a UTC day) starts on the reader's clock today,
+ * "02:00"; empty where it starts at their midnight. `timeZone` is the
+ * reader's (`undefined`: the zone the code runs in).
+ */
+export function utcDayStart(
+  now: number,
+  locale: string,
+  timeZone?: string,
+): string {
+  const today = new Date(now)
+  const utcMidnight = new Date(
+    Date.UTC(today.getUTCFullYear(), today.getUTCMonth(), today.getUTCDate()),
+  )
+  const clock = new Intl.DateTimeFormat('en-US', {
+    hour: 'numeric',
+    minute: 'numeric',
+    hourCycle: 'h23',
+    timeZone,
+  }).format(utcMidnight)
+  if (clock === '0:00' || clock === '00:00') {
+    return ''
+  }
+  return new Intl.DateTimeFormat(locale, {
+    hour: '2-digit',
+    minute: '2-digit',
+    timeZone,
+  }).format(utcMidnight)
+}
+
+/** "Sep 29", in `timeZone` (`undefined`: the zone the code runs in). */
+export function formatShortDate(
+  at: number | Date,
+  locale: string,
+  timeZone?: string,
+): string {
   return new Intl.DateTimeFormat(locale, {
     month: 'short',
     day: 'numeric',
+    timeZone,
   }).format(at)
 }
 

package/frontend-vue/package.json

@@ -7,7 +7,7 @@
   "license": "Apache-2.0",
   "packageManager": "pnpm@10.6.5",
   "engines": {
-    "@antelopejs/dms-frontend": ">=0.5.2 <0.6.0"
+    "@antelopejs/dms-frontend": ">=0.6.0 <0.7.0"
   },
   "scripts": {
     "dev": "pnpm --dir ../playground frontend:dev",

package/frontend-vue/tests/format.test.ts

@@ -2,9 +2,11 @@ import { describe, expect, it } from 'vitest'
 import {
   displayName,
   formatDuration,
+  formatShortDate,
   formatSignedDelta,
   initials,
   percentChangeTrend,
+  utcDayStart,
 } from '../app/utils/format'
 import { sampleSizePerArm } from '../app/utils/sample-size'
 import { normalizeFunnelStepPath } from '../app/utils/step-path'
@@ -71,3 +73,22 @@ describe('helpers', () => {
     ).toContain('"data-website-id": "site-1"')
   })
 })
+
+describe('dates in the reader zone', () => {
+  // 16 Oct 2026: Paris on summer time (UTC+2), New York on UTC-4.
+  const now = Date.UTC(2026, 9, 16, 12)
+
+  it('says when the statistics day starts on the reader clock, nothing at UTC', () => {
+    expect(utcDayStart(now, 'en-GB', 'Europe/Paris')).toBe('02:00')
+    expect(utcDayStart(now, 'en-GB', 'America/New_York')).toBe('20:00')
+    expect(utcDayStart(now, 'en-GB', 'UTC')).toBe('')
+  })
+
+  it('writes a short date on the reader day, wherever the code runs', () => {
+    const lateEvening = Date.UTC(2026, 9, 16, 2)
+    expect(formatShortDate(lateEvening, 'en', 'Europe/Paris')).toBe('Oct 16')
+    expect(formatShortDate(lateEvening, 'en', 'America/New_York')).toBe(
+      'Oct 15',
+    )
+  })
+})