@antelopejs/dms-marketing 0.4.0 → 0.5.0

package/frontend-vue/app/components/WebsitesGrid.vue

@@ -1,11 +1,16 @@
 <script setup lang="ts">
-import { computed, onBeforeUnmount, onMounted, ref } from 'vue'
+import { computed, ref } from 'vue'
 import { useDmsRouter, useI18n } from '#dms/frontend-module'
 import {
   useMarketingApi,
   type MarketingWebsiteCard,
 } from '../composables/useMarketingApi'
 import { installLink, overviewLink } from '../composables/useMarketingRoutes'
+import {
+  useWebsiteCards,
+  useWebsiteDeletionImpactRead,
+} from '../composables/useMarketingReads'
+import { useMarketingNow } from '../composables/useMarketingNow'
 import {
   formatNumber,
   formatRelativeTime,
@@ -51,25 +56,23 @@ const { confirm } = useConfirm()
 
 void props
 
-const cards = ref<MarketingWebsiteCard[] | null>(null)
-const failed = ref(false)
+const cardsRead = useWebsiteCards()
+const cards = cardsRead.data
+/** The cards could not be read; shown once a retry is over. */
+const failed = computed(
+  () => !!cardsRead.error.value && cardsRead.status.value !== 'pending',
+)
 
-async function load(): Promise<void> {
-  failed.value = false
-  try {
-    cards.value = await api.listWebsiteCards()
-  } catch {
-    failed.value = true
-  }
-}
+/** The cards again: a retry after a failed read. */
+const load = (): Promise<void> => cardsRead.refresh()
 
-const now = ref(Date.now())
-let clock: ReturnType<typeof setInterval> | null = null
-onMounted(() => {
-  void load()
-  clock = setInterval(() => (now.value = Date.now()), CLOCK_TICK_MS)
-})
-onBeforeUnmount(() => clock && clearInterval(clock))
+/** The website a deletion is asked about. */
+const deletionTarget = ref('')
+const readDeletionImpact = useWebsiteDeletionImpactRead(deletionTarget)
+
+const now = useMarketingNow(CLOCK_TICK_MS)
+/** The browser's zone, which a server render writes the dates in. */
+const readerZone = readerTimeZone()
 
 function stateLine(card: MarketingWebsiteCard): string {
   if (card.state === 'live' && card.lastActivityAt) {
@@ -106,7 +109,9 @@ async function runCardAction(
   try {
     await action()
     toast.add({ color: 'success', title: successTitle })
-    await load()
+    // Their state and counts are the backend's: the page reads them again,
+    // the card's spinner on until it shows them.
+    await refreshPageBlocks()
   } catch (error) {
     const conflict = hostConflictOf(error)
     if (conflict) {
@@ -226,7 +231,7 @@ async function save(): Promise<void> {
     })
     toast.add({ color: 'success', title: t('page.marketing.websites.saved') })
     drawerOpen.value = false
-    await load()
+    refreshPageBlocks()
   } catch (error) {
     // A refused field lives on the General tab: show it there.
     const conflict = hostConflictOf(error)
@@ -253,7 +258,8 @@ async function save(): Promise<void> {
 async function remove(card: MarketingWebsiteCard): Promise<void> {
   let impact
   try {
-    impact = await api.getWebsiteDeletionImpact(card.id)
+    deletionTarget.value = card.id
+    impact = await readDeletionImpact()
   } catch (error) {
     fieldErrors.toastError(error, {
       toastTitle: 'page.marketing.websites.delete.impact_error',
@@ -305,7 +311,8 @@ async function remove(card: MarketingWebsiteCard): Promise<void> {
         title: t('page.marketing.websites.delete.done', { name: card.name }),
       })
       drawerOpen.value = false
-      await load()
+      // Its card goes; the others are unchanged, so nothing is read again.
+      cards.value = cards.value?.filter((other) => other.id !== card.id) ?? null
     },
   })
 }
@@ -565,7 +572,9 @@ async function remove(card: MarketingWebsiteCard): Promise<void> {
                   card.rejected.length > 0
                     ? 'page.marketing.websites.waiting_refused'
                     : 'page.marketing.websites.waiting_description',
-                  { date: formatShortDate(card.createdAt, locale) },
+                  {
+                    date: formatShortDate(card.createdAt, locale, readerZone),
+                  },
                 )
               }}
             </p>

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')
+}