frappe-ui 1.0.0-beta.18 → 1.0.0-beta.19

package/frappe/telemetry/index.ts

@@ -1,9 +1,17 @@
 import { reactive, readonly, ref, type App } from 'vue'
+import type { Router, RouteLocationNormalized } from 'vue-router'
 
-import { pulse_provider, PulseProvider } from './pulse.ts'
-import { silentCall } from './utils.ts'
+import {
+  fetchBootConfig,
+  loadPulseClient,
+  type BootConfig,
+  type PulseAnonymousMode,
+  type PulseClient,
+  type PulseContext,
+} from './pulse.ts'
 
-let pulseProvider: PulseProvider | null = null
+let client: PulseClient | null = null
+let removePageviewHook: (() => void) | null = null
 
 const appName = ref<string>()
 const isEnabled = ref(false)
@@ -13,18 +21,39 @@ export function useTelemetry() {
     isEnabled: readonly(isEnabled),
     disable: () => {
       isEnabled.value = false
-      pulseProvider?.setEnabled(false)
-      pulseProvider?.stop()
+      client?.stop()
     },
     capture: (event_name: string, data: Record<string, any> = {}) => {
       if (!isEnabled.value || !appName.value) return
-      pulseProvider?.capture(event_name, appName.value, data)
+      client?.capture(event_name, appName.value, data)
     },
+    getDistinctId: () => client?.getDistinctId?.() ?? '',
   })
 }
 
+export interface TelemetryPluginOptions {
+  app_name: string
+  host?: string
+  apiKey?: string
+  site?: string
+  enabled?: boolean
+  getContext?: () => PulseContext
+  anonymousMode?: PulseAnonymousMode
+  clientUrl?: string
+  // Pass your vue-router to auto-capture a "pageview" per navigation (new sites only,
+  // site_age <= 15 days, like desk).
+  router?: Router
+  // Route → PII-safe string. Defaults to the matched path pattern (e.g. "/orders/:id").
+  scrubRoute?: (to: RouteLocationNormalized) => string
+}
+
+function defaultScrubRoute(to: RouteLocationNormalized): string {
+  const matched = to.matched[to.matched.length - 1]
+  return matched?.path || to.path || ''
+}
+
 export default {
-  async install(app: App, options: { app_name: string }) {
+  async install(app: App, options: TelemetryPluginOptions) {
     appName.value = options.app_name
 
     if (!appName.value) {
@@ -36,13 +65,58 @@ export default {
       return
     }
 
-    isEnabled.value = await silentCall<boolean>(
-      'frappe.utils.telemetry.pulse.client.is_enabled',
-    )
-    if (!isEnabled.value) return
+    // Explicit options win; fetch the rest from the backend (skip when self-sufficient).
+    const fetched: BootConfig =
+      options.host != null && options.apiKey != null ? {} : await fetchBootConfig()
+
+    const getContext =
+      options.getContext || (() => ({ user: fetched.user, team: fetched.team }))
+
+    // Reinstalls (tests, HMR, SSR-per-request) reuse the module singletons, so tear
+    // down the previous client's flush timer and router hook before replacing them.
+    client?.stop()
+    removePageviewHook?.()
+    removePageviewHook = null
+
+    client = await loadPulseClient({
+      host: options.host ?? fetched.host,
+      apiKey: options.apiKey ?? fetched.key,
+      site: options.site ?? fetched.site,
+      enabled: options.enabled ?? fetched.enabled ?? false,
+      getContext,
+      anonymousMode: options.anonymousMode,
+      clientUrl: options.clientUrl ?? fetched.client_url,
+    })
+    if (!client) return
 
-    pulseProvider = pulse_provider
-    pulseProvider.setEnabled(true)
-    pulseProvider.init()
+    isEnabled.value = await client.init()
+    if (isEnabled.value) {
+      removePageviewHook = setupPageviewTracking(options, fetched.site_age)
+    }
   },
 }
+
+// Older backends omit site_age → track anyway (permissive, matching desk's
+// `site_age && site_age > 15` skip check).
+function setupPageviewTracking(
+  options: TelemetryPluginOptions,
+  site_age: number | undefined,
+): (() => void) | null {
+  if (!options.router || (site_age && site_age > 15)) return null
+
+  const scrub = options.scrubRoute || defaultScrubRoute
+  let lastFullPath = ''
+  const capturePageview = (to: RouteLocationNormalized) => {
+    // Dedupe so the initial capture and afterEach can't double-count the same route.
+    if (!isEnabled.value || !appName.value || to.fullPath === lastFullPath) return
+    lastFullPath = to.fullPath
+    client?.capture('pageview', appName.value, { route: scrub(to) })
+  }
+
+  // afterEach missed the initial navigation if it resolved during install's awaits,
+  // so capture the landing route once the router is ready.
+  options.router.isReady().then(() => {
+    if (options.router) capturePageview(options.router.currentRoute.value)
+  })
+  return options.router.afterEach((to) => capturePageview(to))
+}

package/frappe/telemetry/pulse.ts

@@ -1,181 +1,95 @@
+// Loads the one canonical pulse client from pulse's own CDN (not the host backend),
+// so it's independent of the backend's framework version. Degrades to null if the
+// asset can't be loaded, leaving telemetry off.
+
 import { call } from 'frappe-ui'
 
-type PulseEvent = {
-  captured_at: string
-  event_name: string
-  app: string
+export interface PulseContext {
   user?: string
-  properties?: Record<string, any>
+  team?: string
 }
 
-export class PulseProvider {
-  private enabled: boolean
-  private eq: QueueManager | null
-  private beforeUnloadAttached: boolean
-
-  constructor() {
-    this.enabled = false
-    this.eq = null
-    this.beforeUnloadAttached = false
-  }
-
-  setEnabled(isEnabled: boolean) {
-    this.enabled = isEnabled
-    if (!this.enabled) {
-      this.eq?.stop()
-      this.eq = null
-    }
-  }
-
-  init() {
-    if (!this.enabled) return
-    if (this.eq) return
-
-    try {
-      this.eq = new QueueManager((events) => this.sendEvents(events), {
-        flushInterval: 10000,
-      })
-
-      if (!this.beforeUnloadAttached) {
-        this.beforeUnloadAttached = true
-
-        // Send remaining events on unload
-        window.addEventListener('beforeunload', () => {
-          const events = this.eq?.getBufferedEvents?.() || []
-          if (events.length) this.sendBeacon(events)
-        })
-      }
-    } catch (error: any) {
-      // ignore errors
-    }
-  }
-
-  capture(event: string, app: string, props?: Record<string, any>) {
-    if (!this.enabled || !this.eq) return
-
-    const user = (window as any)?.frappe?.session?.user
-
-    this.eq.add({
-      event_name: event,
-      app: app,
-      properties: props,
-      user,
-      captured_at: new Date().toISOString(),
-    })
-  }
-
-  private async sendEvents(events: PulseEvent[]): Promise<void> {
-    return call('frappe.utils.telemetry.pulse.client.bulk_capture', { events })
-  }
-
-  private sendBeacon(events: PulseEvent[]) {
-    try {
-      if (navigator.sendBeacon) {
-        const url =
-          '/api/method/frappe.utils.telemetry.pulse.client.bulk_capture'
-        const data = new FormData()
-        data.append('events', JSON.stringify(events))
-        navigator.sendBeacon(url, data)
-      }
-    } catch (error: any) {
-      // ignore errors
-    }
-  }
-
-  stop() {
-    this.eq?.stop()
-    this.eq = null
-  }
-}
-
-type QueueManagerOptions = {
-  maxQueueSize?: number
+// "cookieless" (default): host derives the anon id at ingest. "client": mints a
+// persistent localStorage anon id.
+export type PulseAnonymousMode = 'cookieless' | 'client'
+
+export interface PulseClientOptions {
+  host?: string
+  apiKey?: string
+  site?: string
+  enabled?: boolean
+  getContext?: () => PulseContext
+  anonymousMode?: PulseAnonymousMode
   flushInterval?: number
+  maxQueueSize?: number
+  now?: () => string
+  clientUrl?: string
 }
 
-class QueueManager {
-  private flushCallback: (events: PulseEvent[]) => Promise<void>
-  private queue: PulseEvent[]
-  private pendingBatch: PulseEvent[] | null
-  private retryAttempts: number
-  private maxRetries: number
-  private maxQueueSize: number
-  private flushInterval: number
-  private timer: ReturnType<typeof setInterval> | null
-  private flushing: boolean
-
-  constructor(
-    flushCallback: (events: PulseEvent[]) => Promise<void>,
-    options: QueueManagerOptions = {},
-  ) {
-    this.flushCallback = flushCallback
-    this.queue = []
-    this.pendingBatch = null
-    this.retryAttempts = 0
-    this.maxRetries = 3
-    this.maxQueueSize = options.maxQueueSize || 20
-    this.flushInterval = options.flushInterval || 5000
-    this.timer = null
-    this.flushing = false
-
-    this.start()
-  }
-
-  getBufferedEvents() {
-    const events: PulseEvent[] = []
-    if (this.pendingBatch?.length) events.push(...this.pendingBatch)
-    if (this.queue.length) events.push(...this.queue)
-    return events
-  }
+export interface PulseClient {
+  init(): Promise<boolean>
+  setEnabled(enabled: boolean): void
+  capture(event_name: string, app: string, props?: Record<string, any>): void
+  // Distinct id on events (known identity, else anon id); used to alias() pre-signup
+  // activity. Optional: an older CDN build may not expose it.
+  getDistinctId?(): string
+  flush(): Promise<void> | undefined
+  stop(): void
+}
 
-  private start() {
-    this.timer = setInterval(() => {
-      if (this.queue.length || this.pendingBatch) this.flush()
-    }, this.flushInterval)
-  }
+// Shape returned by the framework's whitelisted boot_config method.
+export interface BootConfig {
+  enabled?: boolean
+  host?: string
+  key?: string
+  site?: string
+  user?: string
+  team?: string
+  client_url?: string
+  site_age?: number
+}
 
-  add(event: PulseEvent) {
-    this.queue.push(event)
+export const BOOT_CONFIG_METHOD = 'frappe.utils.telemetry.pulse.client.boot_config'
 
-    if (this.queue.length >= this.maxQueueSize) {
-      this.flush()
-    }
+// Direct-mode config from the app's own backend (frappe-ui SPAs lack desk's
+// window.frappe.boot). Degrades to {} on any error, including old backends (404).
+export async function fetchBootConfig(): Promise<BootConfig> {
+  try {
+    return (await call(BOOT_CONFIG_METHOD)) || {}
+  } catch (error) {
+    return {}
   }
+}
 
-  async flush() {
-    if (this.flushing) return
-    this.flushing = true
-
+export const DEFAULT_PULSE_CLIENT_URL =
+  'https://pulse.m.frappe.cloud/assets/pulse/js/pulse_client.js'
+
+// Only import from a trusted origin: pulse's CDN or the ingest host (self-hosted
+// pulse). Stops a tampered boot_config from redirecting import() to an attacker
+// origin — an untrusted url falls back to the canonical CDN.
+function trustedClientUrl(clientUrl: string | undefined, host?: string): string {
+  if (!clientUrl) return DEFAULT_PULSE_CLIENT_URL
+  try {
+    const target = new URL(clientUrl)
+    if (target.protocol !== 'https:') return DEFAULT_PULSE_CLIENT_URL
+    const allowed = new Set([new URL(DEFAULT_PULSE_CLIENT_URL).origin])
     try {
-      if (!this.pendingBatch) {
-        if (!this.queue.length) return
-        this.pendingBatch = this.queue.splice(0, this.maxQueueSize)
-        this.retryAttempts = 0
-      }
-
-      try {
-        await this.flushCallback(this.pendingBatch)
-        this.pendingBatch = null
-        this.retryAttempts = 0
-      } catch (error: any) {
-        this.retryAttempts++
-        if (this.retryAttempts > this.maxRetries) {
-          this.pendingBatch = null
-          this.retryAttempts = 0
-        }
-      }
-    } finally {
-      this.flushing = false
-    }
-  }
+      if (host) allowed.add(new URL(host).origin)
+    } catch {}
+    if (allowed.has(target.origin)) return clientUrl
+  } catch {}
+  return DEFAULT_PULSE_CLIENT_URL
+}
 
-  stop() {
-    if (this.timer) {
-      clearInterval(this.timer)
-      this.timer = null
-    }
-    void this.flush()
+export async function loadPulseClient(
+  options: PulseClientOptions = {},
+): Promise<PulseClient | null> {
+  const { clientUrl, ...clientOptions } = options
+  try {
+    const url = trustedClientUrl(clientUrl, clientOptions.host)
+    const mod = await import(/* @vite-ignore */ url)
+    return new mod.PulseClient(clientOptions) as PulseClient
+  } catch (error) {
+    return null
   }
 }
-
-export const pulse_provider = new PulseProvider()

package/frappe/telemetry/telemetry.test.ts

@@ -2,86 +2,20 @@
  * @vitest-environment jsdom
  */
 
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { PulseProvider } from './pulse'
-
-vi.mock('frappe-ui', () => ({
-  call: vi.fn().mockResolvedValue({}),
-}))
-
-describe('PulseProvider', () => {
-  let provider: PulseProvider
-
-  beforeEach(() => {
-    provider = new PulseProvider()
-  })
-
-  it('is disabled by default', () => {
-    const result = provider.capture('test', 'app')
-    expect(result).toBeUndefined()
-  })
-
-  it('captures events after being enabled and initialized', () => {
-    provider.setEnabled(true)
-    provider.init()
-
-    // Should not throw
-    expect(() => {
-      provider.capture('user_login', 'test_app', { user: 'test@example.com' })
-    }).not.toThrow()
-  })
-
-  it('stops capturing events when disabled', () => {
-    provider.setEnabled(true)
-    provider.init()
-    provider.capture('event1', 'app')
-
-    provider.setEnabled(false)
-
-    // Should not throw
-    expect(() => {
-      provider.capture('event2', 'app')
-    }).not.toThrow()
+import { describe, expect, it } from 'vitest'
+import { loadPulseClient, fetchBootConfig } from './pulse'
+
+// The queue / transport / capture logic lives in the canonical pulse client,
+// loaded at runtime from pulse's CDN (version-independent of the frappe backend).
+// frappe-ui's only job is to load it and its config and degrade gracefully when
+// neither is available — which is exactly the case in the test environment, where
+// the remote asset URL and the backend method can't be resolved.
+describe('telemetry plugin', () => {
+  it('degrades to null when the client asset cannot be loaded', async () => {
+    expect(await loadPulseClient()).toBeNull()
   })
 
-  it('sends events to correct API endpoint', async () => {
-    const { call } = await import('frappe-ui')
-    const mockCall = call as any
-
-    provider.setEnabled(true)
-    provider.init()
-
-    const testEvents = [
-      {
-        event_name: 'test_event',
-        app: 'test_app',
-        captured_at: new Date().toISOString(),
-      },
-    ]
-
-    await provider['sendEvents'](testEvents)
-
-    expect(mockCall).toHaveBeenCalledWith(
-      'frappe.utils.telemetry.pulse.client.bulk_capture',
-      { events: testEvents },
-    )
-  })
-
-  it('batches events before sending', () => {
-    vi.useFakeTimers()
-
-    provider.setEnabled(true)
-    provider.init()
-
-    // Capture multiple events
-    for (let i = 0; i < 5; i++) {
-      provider.capture('event', 'app', { count: i })
-    }
-
-    // Events should be queued, not sent immediately
-    const buffered = provider['eq']?.getBufferedEvents()
-    expect(buffered?.length).toBeGreaterThan(0)
-
-    vi.useRealTimers()
+  it('degrades to {} when the backend config is unreachable (e.g. old framework)', async () => {
+    expect(await fetchBootConfig()).toEqual({})
   })
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frappe-ui",
-  "version": "1.0.0-beta.18",
+  "version": "1.0.0-beta.19",
   "description": "A set of components and utilities for rapid UI development",
   "type": "module",
   "sideEffects": [

package/frappe/telemetry/utils.ts

@@ -1,15 +0,0 @@
-import { call } from 'frappe-ui'
-
-export const silentCall = <T>(method: string): Promise<T> => {
-  // To prevent console errors/logs from being shown
-  // when method doesn't exist in older versions of Frappe
-  const originalError = console.error
-  const originalLog = console.log
-  console.error = () => {}
-  console.log = () => {}
-
-  return call(method).catch(() => {}).finally(() => {
-    console.log = originalLog
-    console.error = originalError
-  })
-}