@antelopejs/dms-marketing 0.6.0 → 0.7.0

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

@@ -0,0 +1,105 @@
+import { computed, type ComputedRef, type Ref } from 'vue'
+import { useDmsRoute, useDmsRouter, useI18n } from '#dms/frontend-module'
+import type {
+  ContextWebsite,
+  MarketingContextPayload,
+} from './useMarketingContext'
+import { useMarketingApi } from './useMarketingApi'
+import { useMarketingContextRead } from './useMarketingReads'
+
+/** The website the page reads, shared by the toolbar's picker and the gate. */
+export interface ContextWebsiteState {
+  context: Ref<MarketingContextPayload | null | undefined>
+  /**
+   * The context could not be read, and none is shown: a failed re-read (an
+   * arrival, a retry) keeps what is shown.
+   */
+  failed: ComputedRef<boolean>
+  websites: ComputedRef<ContextWebsite[]>
+  /** The URL's website, while it is one of the tenant's. */
+  linkedId: ComputedRef<string | null>
+  selectedId: ComputedRef<string | null>
+  selected: ComputedRef<ContextWebsite | null>
+  /** A pick is being saved. */
+  switching: Ref<boolean>
+  select: (id: string) => Promise<void>
+  /** The websites and their last events again; a failure keeps them as is. */
+  reload: () => Promise<void>
+  /** Resolves once the context was read. */
+  ready: PromiseLike<unknown>
+}
+
+/**
+ * The page's website: the URL's `?website=` while it names one of the
+ * tenant's, else the one saved server-side. The toolbar's website picker and
+ * the context gate both call it; they share the context read.
+ */
+export function useContextWebsite(): ContextWebsiteState {
+  const { t } = useI18n()
+  const api = useMarketingApi()
+  const toast = useToast()
+  const route = useDmsRoute()
+  const router = useDmsRouter()
+
+  const contextRead = useMarketingContextRead()
+  const context = contextRead.data
+  const failed = computed(
+    () =>
+      !!contextRead.error.value &&
+      contextRead.status.value !== 'pending' &&
+      !context.value,
+  )
+  const switching = useDmsState('marketing-context-switching', () => false)
+
+  const websites = computed(() => context.value?.websites ?? [])
+  const linkedId = computed(() => {
+    const id = route.query.website
+    return typeof id === 'string' &&
+      websites.value.some((site) => site.id === id)
+      ? id
+      : null
+  })
+  const selectedId = computed(
+    () => linkedId.value ?? context.value?.selectedId ?? null,
+  )
+  const selected = computed<ContextWebsite | null>(
+    () => websites.value.find((site) => site.id === selectedId.value) ?? null,
+  )
+
+  const reload = (): Promise<void> => contextRead.refresh()
+
+  async function select(id: string): Promise<void> {
+    if (id === selectedId.value) {
+      return
+    }
+    switching.value = true
+    try {
+      // Saved first, as the website of the pages opened without one; the
+      // page follows the URL once it names it. A pick is a history entry, so
+      // Back takes it back.
+      context.value = await api.selectContextWebsite(id)
+      await router.push({ query: { ...route.query, website: id } })
+    } catch {
+      toast.add({
+        color: 'error',
+        title: t('page.marketing.context.switch_error'),
+      })
+      await reload()
+    } finally {
+      switching.value = false
+    }
+  }
+
+  return {
+    context,
+    failed,
+    websites,
+    linkedId,
+    selectedId,
+    selected,
+    switching,
+    select,
+    reload,
+    ready: contextRead,
+  }
+}

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

@@ -0,0 +1,47 @@
+import { computed, ref, type ComputedRef, type Ref } from 'vue'
+
+interface UseCopyDraftOptions<T> {
+  /** The form's current values. */
+  values: () => T
+  /** Whether they differ from the form's baseline (`useFormDirty`). */
+  dirty: Ref<boolean> | ComputedRef<boolean>
+  /** Makes the current values the baseline (`useFormDirty`). */
+  markClean: () => void
+}
+
+/**
+ * The unsaved state of a form that can open on a copy (a Duplicate). The copy
+ * is a change to save, so the save bar shows it from the start; but an
+ * untouched copy holds no work to lose: leaving it asks nothing, and closing
+ * the tab or a scripted navigation is never held by a "leave page?" prompt.
+ * Once the user edits it, it is guarded like any other change.
+ */
+export function useCopyDraft<T>(options: UseCopyDraftOptions<T>) {
+  /** The values the copy opened on; null outside a copy. */
+  const copied = ref<string | null>(null)
+  const snapshot = () => JSON.stringify(options.values())
+
+  /** Work leaving would lose: what the leave guard watches. */
+  const unsaved = computed(() =>
+    copied.value === null ? options.dirty.value : snapshot() !== copied.value,
+  )
+
+  /** The copy is applied to the form: what is on screen is the copy. */
+  function open(): void {
+    copied.value = snapshot()
+  }
+
+  /** Ends the copy on what is on screen: the form is clean and nothing holds
+   * the leave. Throwing it away (with any edit to it) and saving it both end it. */
+  function settle(): void {
+    copied.value = null
+    options.markClean()
+  }
+
+  return {
+    isCopy: computed(() => copied.value !== null),
+    unsaved,
+    open,
+    settle,
+  }
+}

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

@@ -24,7 +24,10 @@ export interface MarketingRejectedSource {
   lastAt: number
 }
 
-/** One card of the Websites page (GET /api/marketing/websites/summary). */
+/**
+ * One card of the Websites page: the computed fields a row of the websites
+ * table (GET /api/marketing/tables/websites/list) carries.
+ */
 export interface MarketingWebsiteCard extends ContextWebsite {
   extraDomains: string[]
   snapshotsEnabled: boolean
@@ -37,9 +40,14 @@ export interface MarketingWebsiteCard extends ContextWebsite {
   snapshots: number
   sampleRate: number
   rejected: MarketingRejectedSource[]
+  /** The site `dashboardTracking` provisions: it cannot be deleted. */
+  dashboard: boolean
 }
 
-/** What deleting a website discards (GET /websites/:id/deletion). */
+/**
+ * What deleting a website, or purging its data, discards
+ * (GET /websites/:id/deletion).
+ */
 export interface MarketingWebsiteDeletionImpact {
   /** Every stored day, not a window. */
   sessions: number
@@ -48,6 +56,24 @@ export interface MarketingWebsiteDeletionImpact {
   since: number | null
   funnels: number
   snapshots: number
+  /** Clicks and scrolls, every period: what the heatmaps are drawn from. */
+  heatmapEvents: number
+}
+
+/** What a purge deletes: everything collected, or the heatmaps alone. */
+export type MarketingPurgeScope = 'all' | 'heatmaps'
+
+/** Rows a purge deleted (POST /websites/:id/purge), 0 for what it keeps. */
+export interface MarketingWebsitePurge {
+  purged: string
+  scope: MarketingPurgeScope
+  deleted: {
+    events: number
+    sessions: number
+    days: number
+    snapshots: number
+    imports: number
+  }
 }
 
 export interface MarketingConnectionStatus {
@@ -123,11 +149,18 @@ export interface MarketingPageSnapshot {
   exact: boolean
   capturedAt: number
   origin: string
+  /** Origin and path captured — never a query string or fragment; absent
+   * from an older backend. */
+  url?: string
   viewport: { width: number; height: number }
   document: { width: number; height: number }
   colorScheme?: 'light' | 'dark'
   bytes: number
+  /** The upload cap in force; absent from an older backend. */
+  maxBytes?: number
   html: string | null
+  /** Text masked by the backend: a capture of another workspace. */
+  masked?: boolean
 }
 
 export interface MarketingPageSnapshotResponse {
@@ -135,6 +168,30 @@ export interface MarketingPageSnapshotResponse {
   snapshot: MarketingPageSnapshot | null
 }
 
+/** A workspace the dashboard's heatmaps can be read for (platform owners). */
+export interface MarketingWorkspace {
+  id: string
+  name: string
+  /** The viewer's own workspace. */
+  current: boolean
+}
+
+export interface MarketingWorkspaces {
+  /** Empty: no selector (not a platform owner, a customer website, or a
+   * single workspace). */
+  workspaces: MarketingWorkspace[]
+}
+
+/** What was captured of one path, every layout together. */
+export interface MarketingPageSnapshotSummary {
+  /** The newest capture with a document, else the newest oversize report. */
+  capturedAt: number
+  /** Layouts holding a document, widest first. */
+  layouts: MarketingSnapshotLayout[]
+  /** Only oversize reports: the page is too heavy to capture. */
+  tooHeavy: boolean
+}
+
 /** One observed path of a tracked site, over the requested window. */
 export interface MarketingPageEntry {
   path: string
@@ -142,6 +199,9 @@ export interface MarketingPageEntry {
   clicks: number
   /** Page loads sampled for clicks and scrolls, as counted. */
   sampled: number
+  /** Null for no capture; absent while the site has snapshots off (or from
+   * an older backend). */
+  snapshot?: MarketingPageSnapshotSummary | null
 }
 
 /**
@@ -171,6 +231,8 @@ export interface MarketingPages {
   sampleRate: number | null
   /** Global collection switch; off means nothing new is being recorded. */
   trackerEnabled: boolean
+  /** The site's snapshot option; absent from an older backend. */
+  snapshotsEnabled?: boolean
 }
 
 export interface MarketingFunnelStep {
@@ -344,6 +406,8 @@ export interface MarketingFunnelResults {
   /** The same funnel over the comparison window; null on a split, without
    * one, or when raw events do not cover it. */
   previous?: MarketingFunnelComputation | null
+  /** What the period is compared with; null without a comparison window. */
+  comparison?: 'previous-period' | 'previous-year' | null
   coverage?: MarketingFunnelCoverage
 }
 
@@ -399,6 +463,24 @@ export interface MarketingDashboardTracking {
 
 // --- Facade -----------------------------------------------------------------
 
+type MarketingApi = ReturnType<typeof useMarketingApi>
+
+/**
+ * Writes a funnel definition, creating it when no id is given, and answers
+ * the id of the definition written.
+ */
+export async function saveFunnel(
+  api: Pick<MarketingApi, 'createFunnel' | 'updateFunnel'>,
+  input: MarketingFunnelInput,
+  funnelId?: string,
+): Promise<string> {
+  if (!funnelId) {
+    return (await api.createFunnel(input))._id
+  }
+  await api.updateFunnel(funnelId, input)
+  return funnelId
+}
+
 export function useMarketingApi() {
   const { $authFetch } = useAuthFetch()
 
@@ -427,6 +509,12 @@ export function useMarketingApi() {
         { method: 'DELETE' },
       ),
 
+    purgeWebsite: (website: string, scope: MarketingPurgeScope) =>
+      $authFetch<MarketingWebsitePurge>(
+        `/api/marketing/websites/${encodeURIComponent(website)}/purge`,
+        { method: 'POST', body: { scope } },
+      ),
+
     previewFunnel: (
       website: string,
       steps: MarketingFunnelStep[],
@@ -454,9 +542,9 @@ export function useMarketingApi() {
 
     // 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.
+    // answers the created row, its `_id` included (interface-data-api 0.3).
     createFunnel: (input: MarketingFunnelInput) =>
-      $authFetch<string[]>('/api/marketing/tables/funnels/new', {
+      $authFetch<MarketingFunnelListItem>('/api/marketing/tables/funnels/new', {
         method: 'POST',
         body: input,
       }),

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

@@ -14,8 +14,8 @@ import type {
   MarketingScrollDepth,
   MarketingSnapshotLayout,
   MarketingWebsite,
-  MarketingWebsiteCard,
   MarketingWebsiteDeletionImpact,
+  MarketingWorkspaces,
 } from './useMarketingApi'
 
 /**
@@ -26,8 +26,9 @@ import type {
  * 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`.
+ * (`refreshPageBlocks()`) and the events of its realtime topics read every
+ * one of them again but the context bar's, which reads through its own
+ * live refresh. 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
@@ -47,34 +48,17 @@ function periodRead(
   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.
+ * read again on the bar's own triggers (the page's live gate, its refresh
+ * button), not with the page's blocks.
  */
-export function useMarketingContextRead(
-  options: ContextReadOptions = {},
-): ApiDataResult<MarketingContextPayload> {
+export function useMarketingContextRead(): 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')
@@ -104,6 +88,9 @@ export interface PageInventoryRequest {
   period: MaybeRefOrGetter<MarketingPeriod>
   search: MaybeRefOrGetter<string>
   sort: MaybeRefOrGetter<MarketingPagesSort>
+  /** Another workspace's dashboard, or `all` (see useDashboardWorkspaces);
+   * empty for the website's own data. */
+  workspace?: MaybeRefOrGetter<string>
 }
 
 /** The paths a website's visitors loaded over the period. */
@@ -120,6 +107,7 @@ export function usePageInventory(
         website: toValue(request.websiteId),
         search: toValue(request.search),
         sort: toValue(request.sort),
+        workspace: toValue(request.workspace) || undefined,
       }),
     },
   )
@@ -171,6 +159,8 @@ export interface PagePreviewRequest {
   websiteId: MaybeRefOrGetter<string | undefined>
   path: MaybeRefOrGetter<string>
   period: MaybeRefOrGetter<MarketingPeriod>
+  /** As PageInventoryRequest's. */
+  workspace?: MaybeRefOrGetter<string | undefined>
 }
 
 function previewRead<T>(
@@ -186,6 +176,7 @@ function previewRead<T>(
       query: () => ({
         website: toValue(request.websiteId),
         path: toValue(request.path),
+        workspace: toValue(request.workspace) || undefined,
       }),
       server: false,
     },
@@ -217,6 +208,8 @@ export interface PageSnapshotRequest {
    * backend while the request stays the same, so the capture is read again.
    */
   maskText: MaybeRefOrGetter<boolean>
+  /** As PageInventoryRequest's: the backend masks such a capture. */
+  workspace?: MaybeRefOrGetter<string | undefined>
 }
 
 /** A page's capture in a layout, drawn in the browser. */
@@ -235,6 +228,7 @@ export function usePageSnapshot(
         website: toValue(request.websiteId),
         path: toValue(request.path),
         layout: toValue(request.layout),
+        workspace: toValue(request.workspace) || undefined,
       }),
       watch: [() => toValue(request.maskText)],
       server: false,
@@ -242,6 +236,21 @@ export function usePageSnapshot(
   )
 }
 
+/**
+ * The workspaces a platform owner can read the dashboard's heatmaps of, from
+ * the dashboard's own website; an empty list for anyone else, on any other
+ * website, and on a single-workspace install. Read with the page: the pages
+ * panel shows its selector from the first paint.
+ */
+export function useDashboardWorkspaces(
+  websiteId: MaybeRefOrGetter<string>,
+): ApiDataResult<MarketingWorkspaces> {
+  return useApiData<MarketingWorkspaces>(
+    () => (toValue(websiteId) ? '/api/marketing/stats/workspaces' : null),
+    { query: () => ({ website: toValue(websiteId) }) },
+  )
+}
+
 /** The pages and events a website's visitors sent, for the funnel builder. */
 export function useFunnelSuggestions(
   websiteId: MaybeRefOrGetter<string>,

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

@@ -71,8 +71,31 @@ export function funnelBuilderLink(
   })
 }
 
-export function websitesLink(): string {
-  return `${MODULE_BASE}/websites`
+/** A setting of the Websites page's settings modal a link can open on. */
+export type WebsiteSetting = 'snapshots'
+
+const WEBSITES_PATH = `${MODULE_BASE}/websites`
+
+/**
+ * The Websites page; with `record`, the settings modal of that site open
+ * (the table's deep link), scrolled to `setting` when given — where a
+ * setting shown elsewhere (the heatmap preview's snapshot state) links to.
+ */
+export function websitesLink(
+  record?: string | null,
+  setting?: WebsiteSetting,
+): string {
+  return withQuery(WEBSITES_PATH, {
+    record,
+    setting: record ? setting : null,
+  })
+}
+
+/** The setting a Websites page URL scrolls the open modal to, if any. */
+export function websiteSettingOf(
+  query: Record<string, unknown>,
+): WebsiteSetting | undefined {
+  return query.setting === 'snapshots' ? 'snapshots' : undefined
 }
 
 /** The install guide: a new website, or the one `website` names. */

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

@@ -0,0 +1,17 @@
+import { watch } from 'vue'
+import { useDmsRoute } from '#dms/frontend-module'
+
+/**
+ * Ends the page's breadcrumb with the name of the record it shows ("… ›
+ * Marketing › Checkout funnel") through the DMS's `usePageRecordLabel`, which
+ * a form's `labelKey` uses on stock record pages. A page drawing its own
+ * record (a custom block) names it the same way; while the record is loading
+ * or missing, the page's own name stays.
+ */
+export function useRecordCrumb(name: () => string | null | undefined): void {
+  const route = useDmsRoute()
+  const { setLabel } = usePageRecordLabel()
+  watch(name, (label) => setLabel(route.path, label || undefined), {
+    immediate: true,
+  })
+}

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

@@ -1,4 +1,5 @@
 import { computed, onBeforeUnmount, ref, watch, type Ref } from 'vue'
+import { unrollSnapshotScrollRoot } from '../utils/snapshotScrollRoot'
 
 /**
  * Geometry of a page snapshot rendered in a same-origin, script-less frame.
@@ -10,6 +11,10 @@ import { computed, onBeforeUnmount, ref, watch, type Ref } from 'vue'
  * from a reading taken through it runs away, every `100vh` section growing
  * one tick at a time, exactly as it would with a live page. Once published,
  * later growth is ignored until `reset()`.
+ *
+ * A capture of an app shell scrolling an inner panel is unrolled first (see
+ * snapshotScrollRoot): the reading is then the whole content, not the
+ * visitor's window.
  */
 
 /** Fallback document height when nothing measured it. */
@@ -112,6 +117,7 @@ export function useSnapshotFrame(frame: Ref<HTMLIFrameElement | null>) {
     if (!doc || closed) {
       return
     }
+    unrollSnapshotScrollRoot(doc)
     void (doc.fonts?.ready ?? Promise.resolve()).then(() => {
       if (closed) {
         return
@@ -184,6 +190,26 @@ export function useSnapshotFrame(frame: Ref<HTMLIFrameElement | null>) {
     return boxes
   }
 
+  /**
+   * The anchors whose element the snapshot does not have at all — no
+   * `nth` match, or a selector this document cannot parse. An element that
+   * is there but not drawn at this width (a phone-only menu in a desktop
+   * layout) is not missing: measureAnchors gives it no box, this keeps it.
+   */
+  function missingAnchors(anchors: AnchorRequest[]): AnchorRequest[] {
+    const doc = frameDocument()
+    if (!doc) {
+      return []
+    }
+    return anchors.filter((anchor) => {
+      try {
+        return !doc.querySelectorAll(anchor.selector)[anchor.nth]
+      } catch {
+        return true
+      }
+    })
+  }
+
   onBeforeUnmount(() => {
     watchedFrame?.removeEventListener('load', onFrameLoad)
     watchedFrame = null
@@ -201,5 +227,13 @@ export function useSnapshotFrame(frame: Ref<HTMLIFrameElement | null>) {
     return measuredHeight.value !== null ? 'measured' : 'pending'
   })
 
-  return { measuredWidth, measuredHeight, tier, reset, close, measureAnchors }
+  return {
+    measuredWidth,
+    measuredHeight,
+    tier,
+    reset,
+    close,
+    measureAnchors,
+    missingAnchors,
+  }
 }

package/frontend-vue/app/utils/anchor-drift.ts

@@ -0,0 +1,58 @@
+/**
+ * How many anchored clicks aim at elements the snapshot no longer has: the
+ * sign the page changed since it was captured. Such a click is drawn at
+ * its document fraction instead of on its element (see PagePreview), which
+ * is still a position, not a loss — so the warning waits for a share and a
+ * count that say more than one removed button.
+ */
+
+/** Share of the anchored clicks past which the warning shows. */
+export const DRIFT_MIN_SHARE = 0.1
+/** And the fewest clicks it takes: two clicks out of ten are not a trend. */
+export const DRIFT_MIN_CLICKS = 5
+
+interface DriftPoint {
+  weight: number
+  anchor?: { selector: string; nth: number }
+}
+
+export interface AnchorDrift {
+  /** Clicks carrying an element anchor — the ones that can drift. */
+  anchored: number
+  /** Of those, the clicks whose element is not in the snapshot. */
+  missing: number
+  /** missing / anchored, 0 without anchored clicks. */
+  share: number
+  /** Past both thresholds: worth a warning. */
+  significant: boolean
+}
+
+/**
+ * `isMissing` answers whether an anchor's element is absent from the
+ * snapshot document — absent, not merely hidden at the layout on screen: a
+ * phone menu clicked by phone visitors is in a desktop capture, just not
+ * drawn, and is no sign of change.
+ */
+export function anchorDrift(
+  points: DriftPoint[],
+  isMissing: (anchor: { selector: string; nth: number }) => boolean,
+): AnchorDrift {
+  let anchored = 0
+  let missing = 0
+  for (const point of points) {
+    if (!point.anchor) {
+      continue
+    }
+    anchored += point.weight
+    if (isMissing(point.anchor)) {
+      missing += point.weight
+    }
+  }
+  const share = anchored > 0 ? missing / anchored : 0
+  return {
+    anchored,
+    missing,
+    share,
+    significant: missing >= DRIFT_MIN_CLICKS && share >= DRIFT_MIN_SHARE,
+  }
+}

package/frontend-vue/app/utils/drift-dismissals.ts

@@ -0,0 +1,20 @@
+import { ref } from 'vue'
+
+/**
+ * Pages whose drift warning was dismissed: for the rest of the session (the
+ * tab's lifetime), per website and path, so switching pages and coming back
+ * does not bring it back. A reload does: the drift is still there.
+ */
+const dismissed = ref(new Set<string>())
+
+function key(websiteId: string, path: string): string {
+  return `${websiteId}\u0000${path}`
+}
+
+export function driftDismissed(websiteId: string, path: string): boolean {
+  return dismissed.value.has(key(websiteId, path))
+}
+
+export function dismissDrift(websiteId: string, path: string): void {
+  dismissed.value = new Set(dismissed.value).add(key(websiteId, path))
+}