@morscherlab/mint-sdk 1.3.9 → 1.4.0-beta.2

package/src/composables/usePlatformContext.ts

@@ -1,299 +0,0 @@
-import { ref, computed, onMounted, onUnmounted } from 'vue'
-import type { PlatformContext, PlatformContextOptions, PlatformEvent } from '../types'
-
-const DEFAULT_CONTEXT: PlatformContext = {
-  isIntegrated: false,
-  theme: 'system',
-}
-
-const platformContext = ref<PlatformContext>({ ...DEFAULT_CONTEXT })
-
-// Track allowed origins for postMessage security.
-// Inferred origins come from platform injection and URL params.
-// Consumer origins and allowAnyOrigin are tracked per composable instance.
-let inferredOrigins: Set<string> = new Set()
-let allowedOrigins: Set<string> = new Set()
-let allowAnyOrigin = false
-let initialized = false
-let listenerCount = 0
-let nextConsumerId = 0
-let currentHandler: ((event: MessageEvent) => void) | null = null
-const consumerOrigins: Map<number, Set<string>> = new Map()
-const allowAnyOriginConsumers: Set<number> = new Set()
-
-/**
- * Derive origin from URL (protocol + host)
- */
-function getOriginFromUrl(url: string): string | null {
-  try {
-    const parsed = new URL(url)
-    return parsed.origin
-  } catch {
-    return null
-  }
-}
-
-function normalizeAllowedOrigins(origins: string[] | undefined): Set<string> {
-  const normalized = new Set<string>()
-  if (!origins) {
-    return normalized
-  }
-
-  for (const origin of origins) {
-    normalized.add(getOriginFromUrl(origin) || origin)
-  }
-  return normalized
-}
-
-function recomputeOriginPolicy(): void {
-  allowedOrigins = new Set(inferredOrigins)
-  for (const origins of consumerOrigins.values()) {
-    for (const origin of origins) {
-      allowedOrigins.add(origin)
-    }
-  }
-  allowAnyOrigin = allowAnyOriginConsumers.size > 0
-}
-
-function resetPlatformContextState(): void {
-  inferredOrigins = new Set()
-  allowedOrigins = new Set()
-  allowAnyOrigin = false
-  initialized = false
-  listenerCount = 0
-  currentHandler = null
-  consumerOrigins.clear()
-  allowAnyOriginConsumers.clear()
-  platformContext.value = { ...DEFAULT_CONTEXT }
-}
-
-/**
- * Check if an origin is allowed for postMessage communication
- */
-function isOriginAllowed(origin: string): boolean {
-  // Development mode: allow any origin (must be explicitly enabled)
-  if (allowAnyOrigin) {
-    console.warn('[MINT SDK] postMessage origin validation disabled - only use in development')
-    return true
-  }
-
-  // Same origin is always allowed
-  if (origin === window.location.origin) {
-    return true
-  }
-
-  // Check against allowed origins list
-  return allowedOrigins.has(origin)
-}
-
-/**
- * Platform context composable for plugin integration with MINT Platform.
- *
- * Provides secure communication with the parent platform via postMessage.
- *
- * @param options - Configuration options
- * @param options.allowedOrigins - List of allowed origins for postMessage
- * @param options.allowAnyOrigin - Allow any origin (UNSAFE, development only)
- *
- * @example
- * ```typescript
- * // Basic usage - derives origin from platform injection
- * const { isIntegrated, user, theme } = usePlatformContext()
- *
- * // With explicit allowed origins
- * const { isIntegrated } = usePlatformContext({
- *   allowedOrigins: ['https://mint.example.com']
- * })
- *
- * // Development mode (UNSAFE)
- * const { isIntegrated } = usePlatformContext({
- *   allowAnyOrigin: import.meta.env.DEV
- * })
- * ```
- */
-/** Connects a plugin to the MINT platform via postMessage, exposing user, theme, and experiment context. */
-export function usePlatformContext(options: PlatformContextOptions = {}) {
-  const consumerId = ++nextConsumerId
-  const instanceOrigins = normalizeAllowedOrigins(options.allowedOrigins)
-  const instanceAllowAnyOrigin = options.allowAnyOrigin === true
-
-  function detectPlatform(): void {
-    const detectedOrigins = new Set<string>()
-
-    // Check if running under MINT Platform by looking for platform-injected global
-    const platformData = (window as unknown as { __MINT_PLATFORM__?: PlatformContext }).__MINT_PLATFORM__
-
-    if (platformData) {
-      platformContext.value = {
-        ...platformData,
-        isIntegrated: true,
-      }
-
-      // Derive platform origin from injected data
-      if (platformData.platformOrigin) {
-        detectedOrigins.add(platformData.platformOrigin)
-      } else if (platformData.platformApiUrl) {
-        const origin = getOriginFromUrl(platformData.platformApiUrl)
-        if (origin) {
-          detectedOrigins.add(origin)
-        }
-      }
-    } else {
-      // Check for platform indicator in URL or localStorage
-      const urlParams = new URLSearchParams(window.location.search)
-      const hasPluginParam = urlParams.has('mint-plugin')
-
-      // Try to get platform origin from URL parameter
-      const platformOrigin = urlParams.get('mint-origin')
-      if (platformOrigin) {
-        const origin = getOriginFromUrl(platformOrigin)
-        if (origin) {
-          detectedOrigins.add(origin)
-        }
-      }
-
-      platformContext.value = {
-        isIntegrated: hasPluginParam,
-        theme: (() => {
-          try {
-            const s = localStorage.getItem('mint-settings')
-            if (s) return (JSON.parse(s).theme as 'light' | 'dark' | 'system') || 'system'
-          } catch { /* ignore */ }
-          return 'system'
-        })(),
-        platformOrigin: platformOrigin || undefined,
-      }
-    }
-
-    inferredOrigins = detectedOrigins
-  }
-
-  function handlePlatformMessage(event: MessageEvent): void {
-    // Only accept messages from parent window (platform)
-    if (event.source !== window.parent) return
-
-    // Validate origin for security
-    if (!isOriginAllowed(event.origin)) {
-      console.warn(`[MINT SDK] Rejected postMessage from untrusted origin: ${event.origin}`)
-      return
-    }
-
-    try {
-      const platformEvent = event.data as PlatformEvent
-      if (!platformEvent.type?.startsWith('mint:')) return
-
-      switch (platformEvent.type) {
-        case 'mint:theme-changed':
-          platformContext.value.theme = platformEvent.payload as 'light' | 'dark' | 'system'
-          break
-        case 'mint:user-changed':
-          platformContext.value.user = platformEvent.payload as PlatformContext['user']
-          break
-      }
-    } catch {
-      // Ignore invalid messages
-    }
-  }
-
-  /**
-   * Send a message to the parent platform.
-   * Uses validated target origin for security.
-   */
-  function sendToPlatform(event: PlatformEvent): void {
-    if (!platformContext.value.isIntegrated || window.parent === window) {
-      return
-    }
-
-    // Determine target origin
-    let targetOrigin: string
-
-    if (platformContext.value.platformOrigin) {
-      // Use explicitly configured platform origin
-      targetOrigin = platformContext.value.platformOrigin
-    } else if (allowedOrigins.size > 0) {
-      // Use first allowed origin (typically the platform)
-      targetOrigin = allowedOrigins.values().next().value as string
-    } else if (allowAnyOrigin) {
-      // Development mode fallback
-      targetOrigin = '*'
-      console.warn('[MINT SDK] Using wildcard origin for postMessage - only use in development')
-    } else {
-      // Safety: if no origin is configured, log warning and don't send
-      console.warn('[MINT SDK] Cannot send postMessage: no platform origin configured')
-      return
-    }
-
-    window.parent.postMessage(event, targetOrigin)
-  }
-
-  /**
-   * Request navigation to a path in the platform.
-   */
-  function navigate(path: string): void {
-    sendToPlatform({
-      type: 'mint:navigate',
-      payload: path,
-    })
-  }
-
-  /**
-   * Show a notification in the platform.
-   */
-  function notify(message: string, type: 'success' | 'error' | 'warning' | 'info' = 'info'): void {
-    sendToPlatform({
-      type: 'mint:notification',
-      payload: { message, type },
-    })
-  }
-
-  onMounted(() => {
-    consumerOrigins.set(consumerId, instanceOrigins)
-    if (instanceAllowAnyOrigin) {
-      allowAnyOriginConsumers.add(consumerId)
-    }
-
-    if (!initialized) {
-      detectPlatform()
-      currentHandler = handlePlatformMessage
-      window.addEventListener('message', handlePlatformMessage)
-      initialized = true
-    }
-
-    listenerCount++
-    recomputeOriginPolicy()
-  })
-
-  onUnmounted(() => {
-    consumerOrigins.delete(consumerId)
-    allowAnyOriginConsumers.delete(consumerId)
-
-    listenerCount = Math.max(0, listenerCount - 1)
-    if (listenerCount === 0) {
-      if (currentHandler) {
-        window.removeEventListener('message', currentHandler)
-      }
-      resetPlatformContextState()
-      return
-    }
-
-    recomputeOriginPolicy()
-  })
-
-  const isIntegrated = computed(() => platformContext.value.isIntegrated)
-  const plugin = computed(() => platformContext.value.plugin)
-  const user = computed(() => platformContext.value.user)
-  const theme = computed(() => platformContext.value.theme)
-  const features = computed(() => platformContext.value.features)
-
-  return {
-    context: platformContext,
-    isIntegrated,
-    plugin,
-    user,
-    theme,
-    features,
-    navigate,
-    notify,
-    sendToPlatform,
-  }
-}

package/src/composables/usePresenceHeartbeat.ts

@@ -1,201 +0,0 @@
-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
-}
-
-export interface PresenceHeartbeatResponse {
-  frontend_revision?: string | null
-}
-
-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
-  /** Observe the authenticated response without adding another poller. */
-  onResponse?: (response: PresenceHeartbeatResponse | unknown) => void
-  /** 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 {
-      const response = await send({ client_id: clientId, scope: scope.value })
-      options.onResponse?.(response)
-    } 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,
-  }
-}

package/src/composables/useRuntimeAlignment.ts

@@ -1,184 +0,0 @@
-import {
-  computed,
-  onMounted,
-  onScopeDispose,
-  readonly,
-  ref,
-  toValue,
-  type MaybeRefOrGetter,
-  type Ref,
-} from 'vue'
-
-const RUNTIME_RELOAD_KEY_PREFIX = 'mint:runtime-reload:'
-const REVISION_QUERY_KEY = '__mint_revision'
-const inMemoryReloadGuards = new Set<string>()
-
-interface RuntimeStorage {
-  getItem(key: string): string | null
-  setItem(key: string, value: string): void
-}
-
-interface RuntimeEventTarget {
-  addEventListener(type: 'vite:preloadError', listener: EventListener): void
-  removeEventListener(type: 'vite:preloadError', listener: EventListener): void
-}
-
-interface RuntimeVisibilityTarget {
-  addEventListener(type: 'visibilitychange', listener: EventListener): void
-  removeEventListener(type: 'visibilitychange', listener: EventListener): void
-}
-
-export interface RuntimeRevisionResponse {
-  frontend_revision?: string | null
-}
-
-export interface RuntimeAlignmentOptions {
-  /** Revision embedded in the HTML that booted this tab. */
-  currentRevision?: MaybeRefOrGetter<string | null | undefined>
-  /** Browser visibility seam. */
-  visibility?: () => DocumentVisibilityState
-  /** Current location seam. */
-  currentUrl?: () => string
-  /** Location replacement seam. */
-  replace?: (url: string) => void
-  /** Per-tab recovery guard storage. */
-  storage?: RuntimeStorage | null
-  /** Vite preload error source. */
-  eventTarget?: RuntimeEventTarget | null
-  /** Browser visibility event source. */
-  visibilityTarget?: RuntimeVisibilityTarget | null
-}
-
-export interface UseRuntimeAlignmentReturn {
-  updateAvailable: Readonly<Ref<boolean>>
-  nextRevision: Readonly<Ref<string | null>>
-  observe: (response: RuntimeRevisionResponse | unknown) => void
-  reload: () => void
-  recoverMissingChunk: () => void
-}
-
-function browserStorage(): RuntimeStorage | null {
-  try {
-    return globalThis.sessionStorage ?? null
-  } catch {
-    return null
-  }
-}
-
-function browserEventTarget(): RuntimeEventTarget | null {
-  return typeof globalThis.window === 'undefined' ? null : globalThis.window
-}
-
-function browserVisibilityTarget(): RuntimeVisibilityTarget | null {
-  return typeof globalThis.document === 'undefined' ? null : globalThis.document
-}
-
-function responseRevision(response: RuntimeRevisionResponse | unknown): string | null {
-  if (!response || typeof response !== 'object') return null
-  const value = (response as RuntimeRevisionResponse).frontend_revision
-  return typeof value === 'string' && value ? value : null
-}
-
-/** Keep a loaded MINT frontend aligned with the backend revision serving its scope. */
-export function useRuntimeAlignment(
-  options: RuntimeAlignmentOptions = {},
-): UseRuntimeAlignmentReturn {
-  const storage = options.storage === undefined ? browserStorage() : options.storage
-  const eventTarget = options.eventTarget === undefined ? browserEventTarget() : options.eventTarget
-  const visibilityTarget = options.visibilityTarget === undefined
-    ? browserVisibilityTarget()
-    : options.visibilityTarget
-  const visibility = options.visibility ?? (() => globalThis.document?.visibilityState ?? 'visible')
-  const currentUrl = options.currentUrl ?? (() => globalThis.location?.href ?? '/')
-  const replace = options.replace ?? ((url: string) => globalThis.location?.replace(url))
-  const initialRevision = computed(() => toValue(options.currentRevision) ?? null)
-  const baselineRevision = ref<string | null>(initialRevision.value)
-  const nextRevision = ref<string | null>(null)
-  const updateAvailable = computed(() => nextRevision.value !== null)
-  let wasHidden = false
-
-  function reloadTo(revision: string, guardKind: 'revision' | 'chunk'): void {
-    const guardKey = `${RUNTIME_RELOAD_KEY_PREFIX}${guardKind}:${revision}`
-    const url = new URL(currentUrl(), globalThis.location?.origin ?? 'http://localhost')
-    if (url.searchParams.get(REVISION_QUERY_KEY) === revision) return
-    if (inMemoryReloadGuards.has(guardKey)) return
-    try {
-      if (storage?.getItem(guardKey)) {
-        inMemoryReloadGuards.add(guardKey)
-        return
-      }
-      storage?.setItem(guardKey, '1')
-    } catch {
-      // A blocked sessionStorage must not block recovery.
-    }
-    inMemoryReloadGuards.add(guardKey)
-    url.searchParams.set(REVISION_QUERY_KEY, revision)
-    replace(url.toString())
-  }
-
-  function observe(response: RuntimeRevisionResponse | unknown): void {
-    const revision = responseRevision(response)
-    if (!revision) return
-    const current = initialRevision.value ?? baselineRevision.value
-    if (!current) {
-      baselineRevision.value = revision
-      return
-    }
-    if (revision === current) {
-      wasHidden = false
-      return
-    }
-    if (wasHidden || visibility() === 'hidden') {
-      wasHidden = false
-      reloadTo(revision, 'revision')
-      return
-    }
-    nextRevision.value = revision
-  }
-
-  function reload(): void {
-    if (nextRevision.value) reloadTo(nextRevision.value, 'revision')
-  }
-
-  function recoverMissingChunk(): void {
-    reloadTo(baselineRevision.value ?? initialRevision.value ?? 'unknown', 'chunk')
-  }
-
-  function handlePreloadError(event: Event): void {
-    event.preventDefault()
-    recoverMissingChunk()
-  }
-
-  function handleVisibilityChange(): void {
-    if (visibility() === 'hidden') wasHidden = true
-  }
-
-  onMounted(() => {
-    eventTarget?.addEventListener('vite:preloadError', handlePreloadError)
-    visibilityTarget?.addEventListener('visibilitychange', handleVisibilityChange)
-  })
-  onScopeDispose(() => {
-    eventTarget?.removeEventListener('vite:preloadError', handlePreloadError)
-    visibilityTarget?.removeEventListener('visibilitychange', handleVisibilityChange)
-  })
-
-  return {
-    updateAvailable: readonly(updateAvailable),
-    nextRevision: readonly(nextRevision),
-    observe,
-    reload,
-    recoverMissingChunk,
-  }
-}
-
-/** Read the revision injected into the HTML that started this browser tab. */
-export function getInjectedFrontendRevision(): string | null {
-  if (typeof globalThis.window === 'undefined') return null
-  const runtimeWindow = globalThis.window as typeof globalThis.window & {
-    __MINT_FRONTEND_REVISION__?: string
-    __MINT_PLATFORM__?: { plugin?: { frontend_revision?: string } }
-  }
-  return runtimeWindow.__MINT_PLATFORM__?.plugin?.frontend_revision
-    ?? runtimeWindow.__MINT_FRONTEND_REVISION__
-    ?? null
-}