@morscherlab/mint-sdk 1.1.10 → 1.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morscherlab/mint-sdk",
-  "version": "1.1.10",
+  "version": "1.1.11",
   "description": "MINT Platform SDK — Vue 3 components, composables, and types for plugin development. MINT = Mass-spec INtegrated Toolkit.",
   "type": "module",
   "main": "./dist/index.js",

package/src/__tests__/components/AppTopBarPresence.test.ts

@@ -0,0 +1,47 @@
+import { computed, ref } from 'vue'
+import { mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import AppTopBar from '../../components/AppTopBar.vue'
+
+const heartbeat = vi.hoisted(() => vi.fn((_options: unknown) => ({
+  clientId: 'presence-tab',
+  isRunning: ref(false),
+  sendNow: vi.fn(),
+})))
+
+vi.mock('../../composables/usePresenceHeartbeat', () => ({
+  usePresenceHeartbeat: heartbeat,
+}))
+
+vi.mock('../../composables/usePlatformContext', () => ({
+  usePlatformContext: vi.fn(() => ({
+    isIntegrated: computed(() => true),
+    context: ref({ isIntegrated: true, theme: 'system' }),
+    plugin: computed(() => ({ id: 'LEAF', name: 'Leaf Analysis' })),
+    user: computed(() => undefined),
+    theme: computed(() => 'system' as const),
+    features: computed(() => undefined),
+    navigate: vi.fn(),
+    notify: vi.fn(),
+    sendToPlatform: vi.fn(),
+  })),
+}))
+
+describe('AppTopBar presence', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('should report the integrated plugin id as the presence scope', () => {
+    const wrapper = mount(AppTopBar, { props: { title: 'LEAF' } })
+
+    const options = heartbeat.mock.calls[0]?.[0] as {
+      enabled: { value: boolean }
+      scope: { value: string }
+    }
+    expect({ enabled: options.enabled.value, scope: options.scope.value }).toEqual({
+      enabled: true,
+      scope: 'LEAF',
+    })
+    wrapper.unmount()
+  })
+})

package/src/__tests__/composables/usePresenceHeartbeat.test.ts

@@ -0,0 +1,147 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { defineComponent, nextTick } from 'vue'
+import { mount } from '@vue/test-utils'
+
+import { usePresenceHeartbeat } from '../../composables/usePresenceHeartbeat'
+
+class MemoryStorage implements Pick<Storage, 'getItem' | 'setItem'> {
+  private readonly values = new Map<string, string>()
+
+  getItem(key: string): string | null {
+    return this.values.get(key) ?? null
+  }
+
+  setItem(key: string, value: string): void {
+    this.values.set(key, value)
+  }
+}
+
+function mountHeartbeat(options: Parameters<typeof usePresenceHeartbeat>[0]) {
+  let heartbeat: ReturnType<typeof usePresenceHeartbeat> | undefined
+  const wrapper = mount(defineComponent({
+    setup() {
+      heartbeat = usePresenceHeartbeat(options)
+      return () => null
+    },
+  }))
+  return { wrapper, get heartbeat() { return heartbeat! } }
+}
+
+describe('usePresenceHeartbeat', () => {
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.restoreAllMocks()
+  })
+
+  it('should reuse one sessionStorage client id and send the integrated scope immediately', async () => {
+    const storage = new MemoryStorage()
+    const send = vi.fn().mockResolvedValue(undefined)
+    const first = mountHeartbeat({
+      scope: 'LEAF',
+      enabled: true,
+      storage,
+      createClientId: () => 'tab-1',
+      send,
+    })
+    await nextTick()
+
+    expect(send).toHaveBeenCalledWith({ client_id: 'tab-1', scope: 'LEAF' })
+
+    first.wrapper.unmount()
+    send.mockClear()
+    const second = mountHeartbeat({
+      scope: 'HMDB',
+      enabled: true,
+      storage,
+      createClientId: () => 'tab-2',
+      send,
+    })
+    await nextTick()
+
+    expect({ clientId: second.heartbeat.clientId, payload: send.mock.calls[0]?.[0] }).toEqual({
+      clientId: 'tab-1',
+      payload: { client_id: 'tab-1', scope: 'HMDB' },
+    })
+    second.wrapper.unmount()
+  })
+
+  it('should heartbeat every 30 seconds only while the page is visible', async () => {
+    vi.useFakeTimers()
+    const send = vi.fn().mockResolvedValue(undefined)
+    const visibility = { value: 'visible' }
+    vi.spyOn(document, 'visibilityState', 'get').mockImplementation(
+      () => visibility.value as DocumentVisibilityState,
+    )
+    const { wrapper } = mountHeartbeat({
+      scope: 'platform',
+      enabled: true,
+      storage: new MemoryStorage(),
+      createClientId: () => 'platform-tab',
+      send,
+    })
+    await nextTick()
+    expect(send).toHaveBeenCalledTimes(1)
+
+    await vi.advanceTimersByTimeAsync(30_000)
+    expect(send).toHaveBeenCalledTimes(2)
+
+    visibility.value = 'hidden'
+    document.dispatchEvent(new Event('visibilitychange'))
+    await vi.advanceTimersByTimeAsync(60_000)
+    expect(send).toHaveBeenCalledTimes(2)
+
+    visibility.value = 'visible'
+    document.dispatchEvent(new Event('visibilitychange'))
+    await nextTick()
+    expect(send).toHaveBeenCalledTimes(3)
+
+    wrapper.unmount()
+    await vi.advanceTimersByTimeAsync(60_000)
+    expect(send).toHaveBeenCalledTimes(3)
+  })
+
+  it('should make no request when the caller is standalone', async () => {
+    vi.useFakeTimers()
+    const send = vi.fn().mockResolvedValue(undefined)
+    const { wrapper } = mountHeartbeat({
+      scope: 'LEAF',
+      enabled: false,
+      storage: new MemoryStorage(),
+      createClientId: () => 'standalone-tab',
+      send,
+    })
+    await nextTick()
+    await vi.advanceTimersByTimeAsync(90_000)
+
+    expect(send).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+  it('should keep a page-local id when sessionStorage is unavailable', async () => {
+    const storage = {
+      getItem: vi.fn(() => { throw new Error('blocked') }),
+      setItem: vi.fn(() => { throw new Error('blocked') }),
+    }
+    const send = vi.fn().mockResolvedValue(undefined)
+    const first = mountHeartbeat({
+      scope: 'LEAF',
+      enabled: true,
+      storage,
+      createClientId: () => 'fallback-tab',
+      send,
+    })
+    await nextTick()
+    first.wrapper.unmount()
+    const second = mountHeartbeat({
+      scope: 'HMDB',
+      enabled: true,
+      storage,
+      createClientId: () => 'different-tab',
+      send,
+    })
+    await nextTick()
+
+    expect(second.heartbeat.clientId).toBe('fallback-tab')
+    second.wrapper.unmount()
+  })
+})

package/src/components/AppTopBar.vue

@@ -22,6 +22,7 @@ import AppAvatarMenu from './AppAvatarMenu.vue'
 import AppPluginSwitcher from './AppPluginSwitcher.vue'
 import PluginIcon from './PluginIcon.vue'
 import { usePlatformContext } from '../composables/usePlatformContext'
+import { usePresenceHeartbeat } from '../composables/usePresenceHeartbeat'
 import { APP_EXPERIMENT_KEY } from '../composables/useAppExperiment'
 import {
   currentItemIdFromLocation,
@@ -115,6 +116,11 @@ const emit = defineEmits<{
 const settingsOpen = ref(false)
 const { isIntegrated, plugin } = usePlatformContext()
 const isStandalone = computed(() => !isIntegrated.value)
+const presenceScope = computed(() => plugin.value?.id || plugin.value?.name || '')
+usePresenceHeartbeat({
+  enabled: isIntegrated,
+  scope: presenceScope,
+})
 const appExperiment = inject(APP_EXPERIMENT_KEY, null)
 const canBindExperiment = computed(() => plugin.value?.plugin_type !== 'static')
 

package/src/composables/index.ts

@@ -10,6 +10,13 @@ export { useTheme } from './useTheme'
 export { useToast } from './useToast'
 export { usePlatformContext } from './usePlatformContext'
 export { resolvePluginFrontendBase } from './pluginFrontendBase'
+export {
+  getPresenceClientId,
+  usePresenceHeartbeat,
+  type PresenceHeartbeatOptions,
+  type PresenceHeartbeatPayload,
+  type UsePresenceHeartbeatReturn,
+} from './usePresenceHeartbeat'
 export {
   useForm,
   type ValidationRule,

package/src/composables/usePresenceHeartbeat.ts

@@ -0,0 +1,194 @@
+import {
+  computed,
+  onMounted,
+  onScopeDispose,
+  readonly,
+  ref,
+  toValue,
+  watch,
+  type MaybeRefOrGetter,
+  type Ref,
+} from 'vue'
+
+import { useApi } from './useApi'
+
+const PRESENCE_CLIENT_ID_KEY = 'mint:presence:client-id'
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000
+
+let pageFallbackClientId: string | null = null
+
+export interface PresenceHeartbeatPayload {
+  client_id: string
+  scope: string
+}
+
+interface PresenceDocument {
+  readonly visibilityState: DocumentVisibilityState
+  addEventListener(type: 'visibilitychange', listener: EventListener): void
+  removeEventListener(type: 'visibilitychange', listener: EventListener): void
+}
+
+interface PresenceStorage {
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+}
+
+export interface PresenceHeartbeatOptions {
+  /** Platform, plugin id, or plugin name reported for this browser tab. */
+  scope: MaybeRefOrGetter<string | null | undefined>
+  /** Disable all traffic, including for standalone plugins. */
+  enabled?: MaybeRefOrGetter<boolean>
+  /** Heartbeat interval. Defaults to 30 seconds. */
+  intervalMs?: number
+  /** Test or host storage seam. Defaults to sessionStorage. */
+  storage?: PresenceStorage | null
+  /** Test or host document seam. Defaults to the current document. */
+  document?: PresenceDocument | null
+  /** Test seam for generating the per-tab id. */
+  createClientId?: () => string
+  /** Test or custom transport seam. Defaults to authenticated POST /api/presence/heartbeat. */
+  send?: (payload: PresenceHeartbeatPayload) => Promise<unknown> | unknown
+  /** Test timing seam. Defaults to the browser scheduler. */
+  setInterval?: (callback: () => void, intervalMs: number) => unknown
+  /** Test timing seam. Defaults to the browser scheduler. */
+  clearInterval?: (intervalId: unknown) => void
+}
+
+export interface UsePresenceHeartbeatReturn {
+  clientId: string
+  isRunning: Readonly<Ref<boolean>>
+  sendNow: () => Promise<void>
+}
+
+function defaultClientId(): string {
+  if (typeof globalThis.crypto?.randomUUID === 'function') {
+    return globalThis.crypto.randomUUID()
+  }
+  return `presence-${Date.now()}-${Math.random().toString(36).slice(2)}`
+}
+
+function defaultStorage(): PresenceStorage | null {
+  try {
+    return globalThis.sessionStorage ?? null
+  } catch {
+    return null
+  }
+}
+
+function defaultDocument(): PresenceDocument | null {
+  return typeof globalThis.document === 'undefined' ? null : globalThis.document
+}
+
+/** Return the stable id shared by presence callers in the current browser tab. */
+export function getPresenceClientId(
+  storage: PresenceStorage | null = defaultStorage(),
+  createClientId: () => string = defaultClientId,
+): string {
+  try {
+    const stored = storage?.getItem(PRESENCE_CLIENT_ID_KEY)
+    if (stored) return stored
+  } catch {
+    // Keep the tab usable when storage is blocked.
+  }
+
+  const nextClientId = createClientId()
+  try {
+    if (storage) {
+      storage.setItem(PRESENCE_CLIENT_ID_KEY, nextClientId)
+      return nextClientId
+    }
+  } catch {
+    // Fall through to the page-local fallback when storage is blocked.
+  }
+
+  if (!pageFallbackClientId) pageFallbackClientId = nextClientId
+  return pageFallbackClientId
+}
+
+/** Report one visible integrated MINT browser tab to the platform presence tracker. */
+export function usePresenceHeartbeat(
+  options: PresenceHeartbeatOptions,
+): UsePresenceHeartbeatReturn {
+  const presenceDocument = options.document === undefined ? defaultDocument() : options.document
+  const clientId = getPresenceClientId(
+    options.storage === undefined ? defaultStorage() : options.storage,
+    options.createClientId ?? defaultClientId,
+  )
+  const intervalMs = options.intervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS
+  const scheduleInterval = options.setInterval ?? ((callback: () => void, delayMs: number) => (
+    globalThis.setInterval(callback, delayMs)
+  ))
+  const cancelInterval = options.clearInterval ?? ((intervalId: unknown) => {
+    globalThis.clearInterval(intervalId as ReturnType<typeof globalThis.setInterval>)
+  })
+  if (intervalMs <= 0) throw new Error('Presence heartbeat interval must be positive')
+
+  const api = options.send ? null : useApi({ baseUrl: '/api' })
+  const send = options.send ?? ((payload: PresenceHeartbeatPayload) => (
+    api!.post('/presence/heartbeat', payload)
+  ))
+  const enabled = computed(() => toValue(options.enabled ?? true))
+  const scope = computed(() => toValue(options.scope)?.trim() ?? '')
+  const isRunning = ref(false)
+  let intervalId: unknown | null = null
+  let sending = false
+  let mounted = false
+
+  function isVisible(): boolean {
+    return presenceDocument?.visibilityState !== 'hidden'
+  }
+
+  function shouldRun(): boolean {
+    return mounted && enabled.value && Boolean(scope.value) && isVisible()
+  }
+
+  async function sendNow(): Promise<void> {
+    if (!shouldRun() || sending) return
+    sending = true
+    try {
+      await send({ client_id: clientId, scope: scope.value })
+    } catch {
+      // Presence is advisory and must never break plugin or platform UI.
+    } finally {
+      sending = false
+    }
+  }
+
+  function stop(): void {
+    if (intervalId !== null) cancelInterval(intervalId)
+    intervalId = null
+    isRunning.value = false
+  }
+
+  function start(): void {
+    stop()
+    if (!shouldRun()) return
+    isRunning.value = true
+    void sendNow()
+    intervalId = scheduleInterval(() => void sendNow(), intervalMs)
+  }
+
+  function handleVisibilityChange(): void {
+    start()
+  }
+
+  watch([enabled, scope], start)
+
+  onMounted(() => {
+    mounted = true
+    presenceDocument?.addEventListener('visibilitychange', handleVisibilityChange)
+    start()
+  })
+
+  onScopeDispose(() => {
+    mounted = false
+    presenceDocument?.removeEventListener('visibilitychange', handleVisibilityChange)
+    stop()
+  })
+
+  return {
+    clientId,
+    isRunning: readonly(isRunning),
+    sendNow,
+  }
+}