@antelopejs/dms-marketing 0.3.2 → 0.4.0

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

@@ -0,0 +1,16 @@
+import { useDmsRoute } from '#dms/frontend-module'
+import { PERIOD_SCOPE } from '../constants'
+import { withWebsite } from './useMarketingRoutes'
+
+/**
+ * A link out of the current page, in its context: the website the context
+ * bar keeps in the page URL ({@link withWebsite}) and the period selector's
+ * keys (the DMS `withPeriodQuery`), what the link names itself winning.
+ */
+export function useContextLink(): (link: string) => string {
+  const route = useDmsRoute()
+  return (link) => {
+    const query = route.query as Record<string, unknown>
+    return withPeriodQuery(withWebsite(link, query), query, PERIOD_SCOPE)
+  }
+}

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

@@ -31,8 +31,7 @@ function parseJsonValue(raw: unknown): unknown {
   }
   try {
     return raw ? JSON.parse(raw) : null
-  }
-  catch {
+  } catch {
     return null
   }
 }

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

@@ -16,8 +16,7 @@ export function parseFunnelStepsValue(raw: unknown): FunnelStepDraft[] {
   if (typeof raw === 'string') {
     try {
       parsed = raw ? JSON.parse(raw) : []
-    }
-    catch {
+    } catch {
       parsed = []
     }
   }

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

@@ -67,16 +67,14 @@ export function useLatestRequest<T>(
         return
       }
       data.value = result
-    }
-    catch (cause) {
+    } catch (cause) {
       if (request !== latest) {
         return
       }
       failed.value = true
       error.value = cause
       data.value = null
-    }
-    finally {
+    } finally {
       // A superseded run owns none of the shared state — not even the flag
       // that says the newest one is still in flight.
       if (request === latest) {

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

@@ -6,8 +6,71 @@
  * convention as dms-api's useApiIntrospection).
  */
 
+import type {
+  ContextWebsite,
+  MarketingContextPayload,
+} from './useMarketingContext'
+
 // --- Shapes mirrored from the backend ---------------------------------------
 
+export type {
+  ContextWebsite,
+  MarketingContextPayload,
+} from './useMarketingContext'
+
+export interface MarketingRejectedSource {
+  hostname: string
+  count: number
+  lastAt: number
+}
+
+/** One card of the Websites page (GET /api/marketing/websites/summary). */
+export interface MarketingWebsiteCard extends ContextWebsite {
+  extraDomains: string[]
+  snapshotsEnabled: boolean
+  snapshotMaskText: boolean
+  createdAt: number
+  /** Over the last 30 days, like `pages` (distinct paths). */
+  sessions: number
+  pages: number
+  funnels: number
+  snapshots: number
+  sampleRate: number
+  rejected: MarketingRejectedSource[]
+}
+
+/** What deleting a website discards (GET /websites/:id/deletion). */
+export interface MarketingWebsiteDeletionImpact {
+  /** Every stored day, not a window. */
+  sessions: number
+  pageviews: number
+  /** Oldest stored day; null when nothing was recorded. */
+  since: number | null
+  funnels: number
+  snapshots: number
+}
+
+export interface MarketingConnectionStatus {
+  website: ContextWebsite
+  createdAt: number
+  /** Server time of the check: the `since` of a later "check again". */
+  checkedAt: number
+  /** Newest pageview since `since` (the site's creation by default). */
+  visit: MarketingConnectionVisit | null
+  lastActivityAt: number | null
+  rejected: MarketingRejectedSource[]
+}
+
+export interface MarketingFunnelSuggestion {
+  value: string
+  count: number
+}
+
+export interface MarketingFunnelSuggestions {
+  pages: MarketingFunnelSuggestion[]
+  events: MarketingFunnelSuggestion[]
+}
+
 export interface MarketingWebsite {
   _id: string
   name: string
@@ -16,13 +79,38 @@ export interface MarketingWebsite {
   /** Opt-in: page snapshots store page content. */
   snapshotsEnabled: boolean
   snapshotMaskText?: boolean
+  extraDomains?: string[]
 }
 
 /** Editable website fields; only the keys present are touched. */
 export type MarketingWebsitePatch = Partial<
-  Pick<MarketingWebsite, 'name' | 'domain' | 'snapshotsEnabled' | 'snapshotMaskText'>
+  Pick<
+    MarketingWebsite,
+    | 'name'
+    | 'domain'
+    | 'extraDomains'
+    | 'trackingEnabled'
+    | 'snapshotsEnabled'
+    | 'snapshotMaskText'
+  >
 >
 
+export interface MarketingWebsiteInput {
+  name: string
+  domain: string
+  extraDomains?: string[]
+}
+
+export interface MarketingConnectionVisit {
+  at: number
+  /** Path only. */
+  url: string
+  /** The host the beacons came from, when the backend saw it. */
+  host?: string
+  browser?: string
+  deviceType?: string
+}
+
 export type MarketingSnapshotLayout = 'desktop' | 'tablet' | 'phone'
 
 /**
@@ -35,8 +123,8 @@ export interface MarketingPageSnapshot {
   exact: boolean
   capturedAt: number
   origin: string
-  viewport: { width: number, height: number }
-  document: { width: number, height: number }
+  viewport: { width: number; height: number }
+  document: { width: number; height: number }
   colorScheme?: 'light' | 'dark'
   bytes: number
   html: string | null
@@ -51,104 +139,40 @@ export interface MarketingPageSnapshotResponse {
 export interface MarketingPageEntry {
   path: string
   pageviews: number
+  clicks: number
+  /** Page loads sampled for clicks and scrolls, as counted. */
+  sampled: number
+}
+
+/**
+ * The period a read covers: the DMS period scope's state (`usePeriodScope`),
+ * appended to the URL as its blocks do. Null reads the routes' default.
+ */
+export type MarketingPeriod = Parameters<typeof appendPeriodToUrl>[1]
+
+export type MarketingPagesSort = 'views' | 'clicks'
+
+/** Clicks and scrolls (`events`) and captures of a page or a whole site. */
+export interface MarketingHeatmapData {
+  events: number
+  snapshots: number
 }
 
 export interface MarketingPages {
   pages: MarketingPageEntry[]
+  /** Paths matching the search, listed or not. */
+  total: number
   /** The inventory hit its cap; narrow the search to see the rest. */
   truncated: boolean
-  /** Share of visits capturing clicks — what makes a heatmap sparse. */
-  heatmapSampleRate: number
+  /**
+   * Measured share of page loads sampled for clicks — what makes a heatmap
+   * sparse. Null while the site has too few pageviews to tell.
+   */
+  sampleRate: number | null
   /** Global collection switch; off means nothing new is being recorded. */
   trackerEnabled: boolean
 }
 
-/** The five-way acquisition grouping the backend derives from referrer
- * domain + utm_medium at rollup time. */
-export type MarketingChannel = 'direct' | 'organic' | 'social' | 'referral' | 'paid'
-
-export interface MarketingDayStatistics {
-  day: number
-  pageviews: number
-  sessions: number
-  newVisitors: number
-  customEvents: number
-  /** Counted as transitions: a day un-bouncing sessions opened the day
-   * before can go negative. Clamp before showing a rate. */
-  bouncedSessions: number
-  sessionDurationMs: number
-  topPages: Record<string, number>
-  topEntryPages?: Record<string, number>
-  topExitPages?: Record<string, number>
-  topReferrers: Record<string, number>
-  topUtmSources: Record<string, number>
-  topUtmMediums?: Record<string, number>
-  topUtmCampaigns?: Record<string, number>
-  topUtmTerms?: Record<string, number>
-  topUtmContents?: Record<string, number>
-  topChannels?: Record<string, number>
-  topDevices?: Record<string, number>
-  topBrowsers?: Record<string, number>
-  topCountries?: Record<string, number>
-  topEvents?: Record<string, number>
-  topLanguages?: Record<string, number>
-}
-
-export interface MarketingOverviewTotals {
-  pageviews: number
-  sessions: number
-  newVisitors: number
-  customEvents: number
-  bouncedSessions: number
-  sessionDurationMs: number
-}
-
-export interface MarketingOverview {
-  totals: MarketingOverviewTotals
-  days: MarketingDayStatistics[]
-  topPages: Record<string, number>
-  topEntryPages: Record<string, number>
-  topExitPages: Record<string, number>
-  topReferrers: Record<string, number>
-  topUtmSources: Record<string, number>
-  topUtmMediums: Record<string, number>
-  topUtmCampaigns: Record<string, number>
-  topUtmTerms: Record<string, number>
-  topUtmContents: Record<string, number>
-  topChannels: Record<string, number>
-  topDevices: Record<string, number>
-  topBrowsers: Record<string, number>
-  /** ISO 3166-1 alpha-2 keys; only populated when the deployment configures
-   * a GeoIP database — `geoipEnabled` says whether the card should show. */
-  topCountries: Record<string, number>
-  /** Custom event names by trigger count — which CTA gets clicked. */
-  topEvents: Record<string, number>
-  /** BCP 47 tags as the visitors' browsers report them (`fr`, `fr-FR`). */
-  topLanguages: Record<string, number>
-  geoipEnabled: boolean
-}
-
-/** One (source, medium, campaign) triple observed on new sessions; a blank
- * slot is a UTM parameter the landing URL did not carry. */
-export interface MarketingCampaignEntry {
-  source?: string
-  medium?: string
-  campaign?: string
-  sessions: number
-}
-
-export interface MarketingCampaigns {
-  /** Exhaustive five-key split, not a top list. */
-  channels: Partial<Record<MarketingChannel, number>>
-  campaigns: MarketingCampaignEntry[]
-  /** The table hit its cap; narrow the search to see the rest. */
-  truncated: boolean
-  terms: Record<string, number>
-  contents: Record<string, number>
-  /** Referrer domains across all channels (search and social included). */
-  referrers?: Record<string, number>
-}
-
 export interface MarketingFunnelStep {
   kind: 'url' | 'custom'
   value: string
@@ -195,7 +219,7 @@ export interface MarketingFunnel {
  * list's foreign join — the write path wants the bare id again. */
 export interface MarketingFunnelListItem {
   _id: string
-  websiteId: string | { _id: string, name?: string, domain?: string }
+  websiteId: string | { _id: string; name?: string; domain?: string }
   name: string
   steps: MarketingFunnelStep[] | string
   conversionWindowHours: number
@@ -218,10 +242,15 @@ export interface MarketingFunnelStepResult {
   step: MarketingFunnelStep
   sessions: number
   conversionRate: number
+  /** Events of the window matching the step, in order or not: 0 means the
+   * site never sent it. */
+  matches: number
 }
 
 export interface MarketingFunnelComputation {
   totalSessions: number
+  /** Events read: 0 means the site sent nothing over the window. */
+  events: number
   steps: MarketingFunnelStepResult[]
 }
 
@@ -233,8 +262,13 @@ export interface MarketingVariationResult {
   exposedSessions: number
   computation: MarketingFunnelComputation
   conversionRate: number
+  /** Exposed sessions that reached the goal. */
+  conversions: number
   /** Relative to the control's conversion; null on the control itself. */
   uplift: number | null
+  /** Bounds of `uplift` at the test's level; null wherever pValue is. */
+  upliftLow: number | null
+  upliftHigh: number | null
   /** Two-sided p-value vs the control; null on the control, when the sample
    * is too small, or when the window is truncated. */
   pValue: number | null
@@ -253,8 +287,44 @@ export interface MarketingExperimentSrm {
 export interface MarketingExperimentResults {
   /** Key of the control arm — the experiment's first variation. */
   control: string
+  /** Level each challenger is tested at: .05, split past two arms. */
+  alpha: number
   variations: MarketingVariationResult[]
   srm: MarketingExperimentSrm
+  /** A verdict waits for a full week and a conversions floor per arm. */
+  decision: {
+    days: number
+    minDays: number
+    minConversions: number
+    ready: boolean
+  }
+}
+
+/** What raw events cover of the period and its comparison. */
+export interface MarketingFunnelCoverage {
+  /** First instant covered (epoch ms), null without any raw event. */
+  since: number | null
+  /** The period starts before it. */
+  period: boolean
+  /** The comparison starts before it: `previous` is left out. */
+  previous: boolean
+}
+
+/** A funnel the site's own journeys suggest, for the first-run state. */
+export interface MarketingFunnelTemplate {
+  steps: MarketingFunnelStep[]
+  /** Sessions of the period that matched step 1. */
+  entering: number
+}
+
+/** What a started test says, read once by the server for the report, its
+ * stop dialog and the list: `early` is significant but short of the decision
+ * rule, `withheld` voided by a warning (truncated read, SRM, nothing scored). */
+export interface MarketingExperimentVerdict {
+  kind: 'winner' | 'loser' | 'flat' | 'early' | 'withheld'
+  /** Index of the arm the verdict names, the control being 0; null when no
+   * challenger could be scored. */
+  leader: number | null
 }
 
 export interface MarketingFunnelResults {
@@ -265,10 +335,21 @@ export interface MarketingFunnelResults {
   experiment?: MarketingExperimentResults
   /** The raw-event window hit its cap; verdicts are withheld. */
   truncated: boolean
+  /** Null on a funnel without a started experiment. */
+  verdict?: MarketingExperimentVerdict | null
   /** Epoch ms bounds the numbers cover: the selected period on a plain
    * funnel, the experiment's own run once one is started — a running split
    * ends at "now", a stopped one at its stop. */
-  window: { since: number, until: number }
+  window: { since: number; until: number }
+  /** The same funnel over the comparison window; null on a split, without
+   * one, or when raw events do not cover it. */
+  previous?: MarketingFunnelComputation | null
+  coverage?: MarketingFunnelCoverage
+}
+
+export interface MarketingFunnelPreview {
+  computation: MarketingFunnelComputation
+  truncated: boolean
 }
 
 /**
@@ -300,10 +381,9 @@ export interface MarketingHeatmap {
 }
 
 /**
- * Scroll-depth distribution of one path. `views` counts only sampled views
- * that scrolled at all — a view that never scrolls (every page that fits its
- * screen included) emits no depth — so shares read "of the views that
- * scrolled", never "of all views".
+ * Scroll-depth distribution of one path. Every sampled view reports one
+ * depth, scrolled or not, so `views` is the number of sampled views (events
+ * stored before the tracker did so only cover views that scrolled).
  */
 export interface MarketingScrollDepth {
   views: number
@@ -314,6 +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
@@ -322,12 +406,76 @@ export function useMarketingApi() {
   const { $authFetch } = useAuthFetch()
 
   return {
-    listWebsites: () => $authFetch<MarketingWebsite[]>('/api/marketing/websites'),
+    listWebsites: () =>
+      $authFetch<MarketingWebsite[]>('/api/marketing/websites'),
 
-    createWebsite: (name: string, domain: string) =>
+    getContext: () =>
+      $authFetch<MarketingContextPayload>('/api/marketing/context'),
+
+    createWebsite: (input: MarketingWebsiteInput) =>
       $authFetch<MarketingWebsite>('/api/marketing/websites', {
         method: 'POST',
-        body: { name, domain },
+        body: input,
+      }),
+
+    selectContextWebsite: (website: string) =>
+      $authFetch<MarketingContextPayload>('/api/marketing/context', {
+        method: 'PUT',
+        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`,
+        { method: 'POST', body: { hostname } },
+      ),
+
+    deleteWebsite: (website: string) =>
+      $authFetch<{ deleted: string }>(
+        `/api/marketing/websites/${encodeURIComponent(website)}`,
+        { 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[],
+      conversionWindowHours: number,
+    ) =>
+      $authFetch<MarketingFunnelPreview>('/api/marketing/funnels/preview', {
+        method: 'POST',
+        query: { website },
+        body: { steps, conversionWindowHours },
       }),
 
     updateWebsite: (id: string, patch: MarketingWebsitePatch) =>
@@ -337,55 +485,66 @@ export function useMarketingApi() {
       ),
 
     // Query strings via ofetch's `query` option — encoding is its job.
-    listPages: (website: string, period = '7d', search = '') =>
-      $authFetch<MarketingPages>('/api/marketing/stats/pages', {
-        query: { website, period, search },
-      }),
-
-    getOverview: (website: string, period = '7d') =>
-      $authFetch<MarketingOverview>('/api/marketing/stats/overview', {
-        query: { website, period },
-      }),
-
-    getCampaigns: (website: string, period = '7d', search = '') =>
-      $authFetch<MarketingCampaigns>('/api/marketing/stats/campaigns', {
-        query: { website, period, search },
-      }),
+    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 = '7d') =>
-      $authFetch<MarketingHeatmap>('/api/marketing/stats/heatmap', {
-        query: { website, path, period },
-      }),
+    getHeatmap: (website: string, path: string, period: MarketingPeriod) =>
+      $authFetch<MarketingHeatmap>(
+        periodUrl('/api/marketing/stats/heatmap', period),
+        {
+          query: { website, path },
+        },
+      ),
 
-    getScrollDepth: (website: string, path: string, period = '7d') =>
-      $authFetch<MarketingScrollDepth>('/api/marketing/stats/scroll', {
-        query: { website, path, period },
-      }),
+    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 },
-      }),
+    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.
     resetHeatmap: (website: string, path?: string) =>
-      $authFetch<{ deleted: number }>('/api/marketing/stats/heatmap', {
+      $authFetch<MarketingHeatmapData>('/api/marketing/stats/heatmap', {
         method: 'DELETE',
         query: { website, path },
       }),
 
-    getFunnelResults: (id: string, period = '7d') =>
-      $authFetch<MarketingFunnelResults>(
-        `/api/marketing/funnels/${encodeURIComponent(id)}/results`,
-        { query: { period } },
-      ),
+    /** 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 }>(
+      $authFetch<{ results: MarketingFunnelListItem[]; total: number }>(
         '/api/marketing/tables/funnels/list',
         {
           query: {
@@ -397,6 +556,12 @@ export function useMarketingApi() {
         },
       ),
 
+    // 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.
     createFunnel: (input: MarketingFunnelInput) =>
       $authFetch<string[]>('/api/marketing/tables/funnels/new', {

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

@@ -0,0 +1,55 @@
+import {
+  computed,
+  inject,
+  type ComputedRef,
+  type InjectionKey,
+  type Ref,
+} from 'vue'
+
+export type WebsiteState = 'live' | 'waiting' | 'paused'
+
+export interface ContextWebsite {
+  id: string
+  name: string
+  domain: string
+  state: WebsiteState
+  lastActivityAt: number | null
+}
+
+export interface MarketingContextPayload {
+  websites: ContextWebsite[]
+  selectedId: string | null
+}
+
+/** What the context container hands the blocks it wraps. */
+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>
+}
+
+export const MARKETING_CONTEXT_KEY: InjectionKey<MarketingContextState> =
+  Symbol('dms-marketing-context')
+
+/**
+ * The context of the page the block sits on. Outside a context container (a
+ * block dropped on another page) the website is unknown and the routes fall
+ * back to the caller's own selection. The period is the DMS period scope's
+ * (`usePeriodScope`), which the bar's selector publishes.
+ */
+export function useMarketingContext(): MarketingContextState {
+  return inject(MARKETING_CONTEXT_KEY, () => detachedContext(), true)
+}
+
+function detachedContext(): MarketingContextState {
+  return {
+    websites: computed(() => []),
+    selected: computed(() => null),
+    refreshToken: { value: 0 } as Ref<number>,
+    select: async () => {},
+    reload: async () => {},
+  }
+}