@antelopejs/dms-marketing 0.4.0 → 0.5.0

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",
@@ -24,7 +24,6 @@
     "@vitejs/plugin-vue": "^6.0.0",
     "eslint": "^9.0.0",
     "eslint-plugin-vue": "^10.0.0",
-    "jsdom": "^26",
     "prettier": "^3.5.3",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.0.0",

package/frontend-vue/pnpm-lock.yaml

@@ -24,9 +24,6 @@ importers:
       eslint-plugin-vue:
         specifier: ^10.0.0
         version: 10.11.0(@typescript-eslint/parser@8.70.0(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3))(eslint@9.39.5(jiti@2.7.0))(vue-eslint-parser@10.4.1(eslint@9.39.5(jiti@2.7.0)))
-      jsdom:
-        specifier: ^26
-        version: 26.1.0
       prettier:
         specifier: ^3.5.3
         version: 3.9.7
@@ -2653,6 +2650,7 @@ snapshots:
       '@csstools/css-parser-algorithms': 3.0.5(@csstools/css-tokenizer@3.0.4)
       '@csstools/css-tokenizer': 3.0.4
       lru-cache: 10.4.3
+    optional: true
 
   '@babel/helper-string-parser@7.29.7': {}
 
@@ -2671,12 +2669,14 @@ snapshots:
     dependencies:
       fontkitten: 1.0.3
 
-  '@csstools/color-helpers@5.1.0': {}
+  '@csstools/color-helpers@5.1.0':
+    optional: true
 
   '@csstools/css-calc@2.1.4(@csstools/css-parser-algorithms@3.0.5(@csstools/css-tokenizer@3.0.4))(@csstools/css-tokenizer@3.0.4)':
     dependencies:
       '@csstools/css-parser-algorithms': 3.0.5(@csstools/css-tokenizer@3.0.4)
       '@csstools/css-tokenizer': 3.0.4
+    optional: true
 
   '@csstools/css-color-parser@3.1.0(@csstools/css-parser-algorithms@3.0.5(@csstools/css-tokenizer@3.0.4))(@csstools/css-tokenizer@3.0.4)':
     dependencies:
@@ -2684,12 +2684,15 @@ snapshots:
       '@csstools/css-calc': 2.1.4(@csstools/css-parser-algorithms@3.0.5(@csstools/css-tokenizer@3.0.4))(@csstools/css-tokenizer@3.0.4)
       '@csstools/css-parser-algorithms': 3.0.5(@csstools/css-tokenizer@3.0.4)
       '@csstools/css-tokenizer': 3.0.4
+    optional: true
 
   '@csstools/css-parser-algorithms@3.0.5(@csstools/css-tokenizer@3.0.4)':
     dependencies:
       '@csstools/css-tokenizer': 3.0.4
+    optional: true
 
-  '@csstools/css-tokenizer@3.0.4': {}
+  '@csstools/css-tokenizer@3.0.4':
+    optional: true
 
   '@esbuild/aix-ppc64@0.27.7':
     optional: true
@@ -3830,7 +3833,8 @@ snapshots:
 
   acorn@8.18.0: {}
 
-  agent-base@7.1.4: {}
+  agent-base@7.1.4:
+    optional: true
 
   ajv@6.15.0:
     dependencies:
@@ -3946,6 +3950,7 @@ snapshots:
     dependencies:
       '@asamuzakjp/css-color': 3.2.0
       rrweb-cssom: 0.8.0
+    optional: true
 
   csstype@3.2.3: {}
 
@@ -3953,12 +3958,14 @@ snapshots:
     dependencies:
       whatwg-mimetype: 4.0.0
       whatwg-url: 14.2.0
+    optional: true
 
   debug@4.4.3:
     dependencies:
       ms: 2.1.3
 
-  decimal.js@10.6.0: {}
+  decimal.js@10.6.0:
+    optional: true
 
   deep-is@0.1.4: {}
 
@@ -4012,7 +4019,8 @@ snapshots:
       graceful-fs: 4.2.11
       tapable: 2.3.3
 
-  entities@6.0.1: {}
+  entities@6.0.1:
+    optional: true
 
   entities@7.0.1: {}
 
@@ -4293,6 +4301,7 @@ snapshots:
   html-encoding-sniffer@4.0.0:
     dependencies:
       whatwg-encoding: 3.1.1
+    optional: true
 
   http-proxy-agent@7.0.2:
     dependencies:
@@ -4300,6 +4309,7 @@ snapshots:
       debug: 4.4.3
     transitivePeerDependencies:
       - supports-color
+    optional: true
 
   https-proxy-agent@7.0.6:
     dependencies:
@@ -4307,12 +4317,14 @@ snapshots:
       debug: 4.4.3
     transitivePeerDependencies:
       - supports-color
+    optional: true
 
   human-signals@5.0.0: {}
 
   iconv-lite@0.6.3:
     dependencies:
       safer-buffer: 2.1.2
+    optional: true
 
   ignore@5.3.2: {}
 
@@ -4335,7 +4347,8 @@ snapshots:
     dependencies:
       is-extglob: 2.1.1
 
-  is-potential-custom-element-name@1.0.1: {}
+  is-potential-custom-element-name@1.0.1:
+    optional: true
 
   is-stream@3.0.0: {}
 
@@ -4377,6 +4390,7 @@ snapshots:
       - bufferutil
       - supports-color
       - utf-8-validate
+    optional: true
 
   json-buffer@3.0.1: {}
 
@@ -4513,7 +4527,8 @@ snapshots:
 
   lodash.merge@4.6.2: {}
 
-  lru-cache@10.4.3: {}
+  lru-cache@10.4.3:
+    optional: true
 
   lru-cache@11.5.2: {}
 
@@ -4600,7 +4615,8 @@ snapshots:
     dependencies:
       boolbase: 1.0.0
 
-  nwsapi@2.2.27: {}
+  nwsapi@2.2.27:
+    optional: true
 
   obug@2.2.1: {}
 
@@ -4649,6 +4665,7 @@ snapshots:
   parse5@7.3.0:
     dependencies:
       entities: 6.0.1
+    optional: true
 
   path-exists@4.0.0: {}
 
@@ -4823,13 +4840,16 @@ snapshots:
 
   rope-sequence@1.3.4: {}
 
-  rrweb-cssom@0.8.0: {}
+  rrweb-cssom@0.8.0:
+    optional: true
 
-  safer-buffer@2.1.2: {}
+  safer-buffer@2.1.2:
+    optional: true
 
   saxes@6.0.0:
     dependencies:
       xmlchars: 2.2.0
+    optional: true
 
   scule@1.3.0: {}
 
@@ -4869,7 +4889,8 @@ snapshots:
     dependencies:
       has-flag: 4.0.0
 
-  symbol-tree@3.2.4: {}
+  symbol-tree@3.2.4:
+    optional: true
 
   tailwind-merge@3.7.0: {}
 
@@ -4895,21 +4916,25 @@ snapshots:
 
   tinyrainbow@3.1.1: {}
 
-  tldts-core@6.1.86: {}
+  tldts-core@6.1.86:
+    optional: true
 
   tldts@6.1.86:
     dependencies:
       tldts-core: 6.1.86
+    optional: true
 
   totalist@3.0.1: {}
 
   tough-cookie@5.1.2:
     dependencies:
       tldts: 6.1.86
+    optional: true
 
   tr46@5.1.1:
     dependencies:
       punycode: 2.3.1
+    optional: true
 
   ts-api-utils@2.5.0(typescript@5.9.3):
     dependencies:
@@ -5179,21 +5204,26 @@ snapshots:
   w3c-xmlserializer@5.0.0:
     dependencies:
       xml-name-validator: 5.0.0
+    optional: true
 
-  webidl-conversions@7.0.0: {}
+  webidl-conversions@7.0.0:
+    optional: true
 
   webpack-virtual-modules@0.6.2: {}
 
   whatwg-encoding@3.1.1:
     dependencies:
       iconv-lite: 0.6.3
+    optional: true
 
-  whatwg-mimetype@4.0.0: {}
+  whatwg-mimetype@4.0.0:
+    optional: true
 
   whatwg-url@14.2.0:
     dependencies:
       tr46: 5.1.1
       webidl-conversions: 7.0.0
+    optional: true
 
   wheel-gestures@2.3.0: {}
 
@@ -5208,11 +5238,13 @@ snapshots:
 
   word-wrap@1.2.5: {}
 
-  ws@8.21.3: {}
+  ws@8.21.3:
+    optional: true
 
   xml-name-validator@5.0.0: {}
 
-  xmlchars@2.2.0: {}
+  xmlchars@2.2.0:
+    optional: true
 
   y-protocols@1.0.7(yjs@13.6.32):
     dependencies:

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

package/frontend-vue/tests/marketing-reads.test.ts

@@ -0,0 +1,252 @@
+import { createSSRApp, defineComponent, h, ref, toValue } from 'vue'
+import { renderToString } from 'vue/server-renderer'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  useFunnelTemplates,
+  useHeatmapCountRead,
+  useMarketingContextRead,
+  usePageHeatmap,
+  usePageInventory,
+  usePageSnapshot,
+  useWebsiteConnection,
+  useWebsiteFunnels,
+} from '../app/composables/useMarketingReads'
+import { useMarketingNow } from '../app/composables/useMarketingNow'
+
+/** What a read asked `useApiData` for. */
+interface ReadCall {
+  url: () => string | null
+  options: Record<string, unknown>
+}
+
+let calls: ReadCall[]
+
+const PERIOD = {
+  preset: 'last-7-days',
+  comparison: 'none',
+  range: {
+    from: new Date('2026-10-09T00:00:00.000Z'),
+    to: new Date('2026-10-15T23:59:59.999Z'),
+  },
+  compareRange: null,
+  key: 'last-7-days',
+}
+
+beforeEach(() => {
+  calls = []
+  vi.stubGlobal(
+    'useApiData',
+    (url: unknown, options: Record<string, unknown> = {}) => {
+      calls.push({ url: () => toValue(url as () => string | null), options })
+      return { data: ref(null) }
+    },
+  )
+  // The DMS's own, as the module's blocks append a period.
+  vi.stubGlobal(
+    'appendPeriodToUrl',
+    (url: string, state: typeof PERIOD | null) =>
+      state?.range
+        ? `${url}?from=${state.range.from.toISOString()}&to=${state.range.to.toISOString()}`
+        : url,
+  )
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+const query = (call: ReadCall | undefined) =>
+  toValue(call?.options.query as () => Record<string, unknown>)
+
+describe('the reads the pages render', () => {
+  it('reads nothing bound to the period before there is one, nor without a website', () => {
+    const website = ref('')
+    const period = ref<typeof PERIOD | null>(null)
+    usePageInventory({
+      websiteId: website,
+      period,
+      search: '',
+      sort: 'views',
+    })
+    useFunnelTemplates(website, period)
+    const [pages, templates] = calls
+    expect(pages?.url()).toBeNull()
+    expect(templates?.url()).toBeNull()
+    website.value = 'acme-shop'
+    expect(pages?.url()).toBeNull()
+    period.value = PERIOD
+    expect(pages?.url()).toBe(
+      '/api/marketing/stats/pages?from=2026-10-09T00:00:00.000Z&to=2026-10-15T23:59:59.999Z',
+    )
+    expect(query(pages)).toEqual({
+      website: 'acme-shop',
+      search: '',
+      sort: 'views',
+    })
+    expect(templates?.url()).toContain('/api/marketing/funnels/templates?from=')
+    expect(query(templates)).toEqual({ website: 'acme-shop' })
+  })
+
+  it('lists a website funnels oldest first, read again with the page refresh', () => {
+    useWebsiteFunnels('acme-shop')
+    const [funnels] = calls
+    expect(funnels?.url()).toBe('/api/marketing/tables/funnels/list')
+    expect(query(funnels)).toMatchObject({
+      filter_websiteId: 'is:acme-shop',
+      sortKey: 'createdAt',
+      sortDirection: 'asc',
+    })
+    // No trigger of its own: the page's refreshes read it again.
+    expect(funnels?.options.watch).toBeUndefined()
+    expect(funnels?.options.refreshOnPageRefresh).toBeUndefined()
+    const transform = funnels?.options.transform as (value: unknown) => unknown
+    expect(transform({ results: [{ _id: 'f1' }], total: 1 })).toEqual([
+      { _id: 'f1' },
+    ])
+  })
+
+  it('checks a website connection since a server time, once there is a website', () => {
+    const website = ref('')
+    const since = ref<number | null>(null)
+    useWebsiteConnection(website, since)
+    const [connection] = calls
+    expect(connection?.url()).toBeNull()
+    website.value = 'shop/eu'
+    expect(connection?.url()).toBe(
+      '/api/marketing/websites/shop%2Feu/connection',
+    )
+    expect(query(connection)).toEqual({ since: undefined })
+    since.value = 1_700_000_000_000
+    expect(query(connection)).toEqual({ since: 1_700_000_000_000 })
+  })
+})
+
+describe('useMarketingNow', () => {
+  it('starts from the time the server rendered at, handed to the browser', async () => {
+    const state = new Map<string, { value: unknown }>()
+    const transferred: string[] = []
+    vi.stubGlobal(
+      'useDmsState',
+      (key: string, init: () => unknown, options?: { transfer?: boolean }) => {
+        if (options?.transfer) {
+          transferred.push(key)
+        }
+        if (!state.has(key)) {
+          state.set(key, ref(init()))
+        }
+        return state.get(key)
+      },
+    )
+    state.set('marketing-rendered-at', ref(1_000))
+    const app = createSSRApp(
+      defineComponent({
+        setup: () => {
+          const now = useMarketingNow(15_000)
+          return () => h('span', String(now.value))
+        },
+      }),
+    )
+    expect(await renderToString(app)).toBe('<span>1000</span>')
+    expect(transferred).toEqual(['marketing-rendered-at'])
+  })
+})
+
+describe('the reads with triggers of their own', () => {
+  it('reads the context bar on its own clock, not with the page', () => {
+    useMarketingContextRead({ refreshInterval: 60_000 })
+    const [context] = calls
+    expect(context?.options).toMatchObject({
+      refreshOnPageRefresh: false,
+      refreshInterval: 60_000,
+    })
+  })
+
+  it('polls the connection check when asked to', () => {
+    useWebsiteConnection('acme-shop', null, { refreshInterval: 4000 })
+    const [connection] = calls
+    expect(connection?.options.refreshInterval).toBe(4000)
+  })
+
+  it('follows a reactive polling period, which stops the check at 0', () => {
+    const interval = ref(4000)
+    useWebsiteConnection('acme-shop', null, { refreshInterval: interval })
+    // One read: the polling is the check's own interval, not a second caller.
+    expect(calls).toHaveLength(1)
+    const [connection] = calls
+    const polling = () => toValue(connection?.options.refreshInterval as number)
+    expect(polling()).toBe(4000)
+    interval.value = 0
+    expect(polling()).toBe(0)
+  })
+})
+
+describe('the page preview', () => {
+  it('reads the clicks in the browser only, once there is a site and a path', () => {
+    const website = ref<string | undefined>(undefined)
+    const period = ref<typeof PERIOD | null>(null)
+    usePageHeatmap({ websiteId: website, path: '/pricing', period })
+    const [heatmap] = calls
+    expect(heatmap?.options.server).toBe(false)
+    expect(heatmap?.url()).toBeNull()
+    website.value = 'acme-shop'
+    // Without a period, the route's default window.
+    expect(heatmap?.url()).toBe('/api/marketing/stats/heatmap')
+    period.value = PERIOD
+    expect(heatmap?.url()).toBe(
+      '/api/marketing/stats/heatmap?from=2026-10-09T00:00:00.000Z&to=2026-10-15T23:59:59.999Z',
+    )
+    expect(query(heatmap)).toEqual({ website: 'acme-shop', path: '/pricing' })
+  })
+
+  it('reads no capture while the site keeps none', () => {
+    const enabled = ref(false)
+    usePageSnapshot({
+      websiteId: 'acme-shop',
+      path: '/pricing',
+      layout: 'phone',
+      enabled,
+    })
+    const [snapshot] = calls
+    expect(snapshot?.url()).toBeNull()
+    enabled.value = true
+    expect(snapshot?.url()).toBe('/api/marketing/stats/snapshot')
+    expect(query(snapshot)).toEqual({
+      website: 'acme-shop',
+      path: '/pricing',
+      layout: 'phone',
+    })
+  })
+})
+
+describe('the reads a dialog makes when it asks', () => {
+  it('reads nothing before, then answers or rejects with the read', async () => {
+    const data = ref<unknown>(null)
+    const error = ref<unknown>(null)
+    const execute = vi.fn(async () => {
+      data.value = { events: 3, snapshots: 1 }
+    })
+    vi.stubGlobal(
+      'useApiData',
+      (url: unknown, options: Record<string, unknown> = {}) => {
+        calls.push({ url: () => toValue(url as () => string | null), options })
+        return { data, error, execute }
+      },
+    )
+    const countHeatmap = useHeatmapCountRead('acme-shop', '/pricing')
+    const [count] = calls
+    expect(count?.options).toMatchObject({
+      immediate: false,
+      refreshOnPageRefresh: false,
+    })
+    expect(execute).not.toHaveBeenCalled()
+    expect(count?.url()).toBe('/api/marketing/stats/heatmap/count')
+    expect(query(count)).toEqual({ website: 'acme-shop', path: '/pricing' })
+    await expect(countHeatmap()).resolves.toEqual({ events: 3, snapshots: 1 })
+
+    const failure = new Error('gone')
+    execute.mockImplementationOnce(async () => {
+      error.value = failure
+    })
+    await expect(countHeatmap()).rejects.toBe(failure)
+  })
+})

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

@@ -22,10 +22,6 @@ const BACKEND_ADDRESSED = [
   'ExperimentInput',
 ]
 
-it('declares the DmsMarketing prefix', () => {
-  expect(frontendModule.componentPrefix).toBe('DmsMarketing')
-})
-
 it('registers every backend-addressed component, once, without the prefix', async () => {
   const registerComponent = vi.fn()
   const registerPlugin = vi.fn()

package/frontend-vue/vitest.config.ts

@@ -14,7 +14,9 @@ export default defineConfig({
     },
   },
   test: {
-    environment: 'jsdom',
+    // No test touches the DOM: the suites drive composables, pure helpers
+    // and the module's setup. jsdom only added its boot to every file.
+    environment: 'node',
     include: ['tests/**/*.test.ts'],
   },
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-marketing",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -34,7 +34,7 @@
     "@antelopejs/interface-data-api": ">=0.2.0 <1.0.0",
     "@antelopejs/interface-database": ">=0.1.8 <1.0.0",
     "@antelopejs/interface-database-decorators": ">=0.1.7 <1.0.0",
-    "@antelopejs/interface-dms": ">=0.5.11 <1.0.0",
+    "@antelopejs/interface-dms": ">=0.7.0 <1.0.0",
     "@antelopejs/interface-dms-marketing": ">=0.4.0 <0.5.0",
     "defu": "^6.1.4",
     "maxmind": "^5.0.7",
@@ -76,7 +76,7 @@
   "scripts": {
     "build": "pnpm --filter @antelopejs/interface-dms-marketing build && rimraf dist && tsc",
     "test": "pnpm run test:backend && pnpm run test:layer",
-    "test:backend": "pnpm run build && ajs module test .",
+    "test:backend": "([ -n \"$DMS_PREBUILT\" ] || pnpm run build) && ajs module test .",
     "test:layer": "cd frontend-vue && pnpm test",
     "dev": "ajs project run -w -p playground",
     "frontend:dev": "cd playground && pnpm frontend:dev",