@morscherlab/mint-sdk 1.1.25 → 1.2.0-beta.10

package/src/composables/useMenuKeyboard.ts

@@ -0,0 +1,90 @@
+import { nextTick } from 'vue'
+
+export interface UseMenuKeyboardOptions {
+  /** Returns the currently navigable items inside the open panel, in DOM order. */
+  items: () => HTMLElement[]
+  /** True while the panel is open. */
+  isOpen: () => boolean
+  /** Opens the panel. */
+  open: () => void
+  /** Closes the panel. When `returnFocus` is true, focus should return to the trigger. */
+  close: (returnFocus?: boolean) => void
+}
+
+export interface UseMenuKeyboardReturn {
+  /**
+   * Bind to the trigger's `@keydown`. ArrowDown/Enter/Space open the panel (when
+   * closed) and focus its first item; ArrowUp opens it focused on the last item.
+   */
+  handleTriggerKeydown: (event: KeyboardEvent) => void
+  /**
+   * Bind to the open panel's `@keydown`. ArrowUp/ArrowDown cycle focus with
+   * wraparound, Home/End jump to the first/last item, Escape closes and returns
+   * focus to the trigger, and Tab closes without moving focus.
+   */
+  handlePanelKeydown: (event: KeyboardEvent) => void
+}
+
+/**
+ * Shared keyboard contract for menu- and listbox-style disclosure panels (the
+ * WAI-ARIA menu button pattern). Used by ActionMenu, AppAvatarMenu and DropdownButton,
+ * each pairing it with `useDropdownState` for the disclosure state itself.
+ */
+export function useMenuKeyboard(options: UseMenuKeyboardOptions): UseMenuKeyboardReturn {
+  function focusItem(position: 'first' | 'last') {
+    void nextTick(() => {
+      const items = options.items()
+      const target = position === 'first' ? items[0] : items[items.length - 1]
+      target?.focus()
+    })
+  }
+
+  function handleTriggerKeydown(event: KeyboardEvent) {
+    if (options.isOpen()) return
+
+    if (event.key === 'ArrowDown' || event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault()
+      options.open()
+      focusItem('first')
+      return
+    }
+    if (event.key === 'ArrowUp') {
+      event.preventDefault()
+      options.open()
+      focusItem('last')
+    }
+  }
+
+  function handlePanelKeydown(event: KeyboardEvent) {
+    const items = options.items()
+    const currentIndex = items.indexOf(document.activeElement as HTMLElement)
+
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      options.close(true)
+      return
+    }
+    if (event.key === 'Tab') {
+      options.close()
+      return
+    }
+    if (event.key === 'Home') {
+      event.preventDefault()
+      items[0]?.focus()
+      return
+    }
+    if (event.key === 'End') {
+      event.preventDefault()
+      items[items.length - 1]?.focus()
+      return
+    }
+    if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return
+
+    event.preventDefault()
+    const direction = event.key === 'ArrowDown' ? 1 : -1
+    const nextIndex = (Math.max(currentIndex, 0) + direction + items.length) % items.length
+    items[nextIndex]?.focus()
+  }
+
+  return { handleTriggerKeydown, handlePanelKeydown }
+}

package/src/composables/useOptimisticMutation.ts

@@ -1,4 +1,5 @@
 import { computed, ref, shallowRef, type ComputedRef, type Ref, type ShallowRef } from 'vue'
+import { readErrorMessage } from '../utils/errors'
 
 export interface OptimisticMutationContext<TVariables, TSnapshot> {
   variables: TVariables
@@ -32,7 +33,11 @@ export interface UseOptimisticMutationReturn<TVariables, TData, TSnapshot = unkn
   reset: () => void
 }
 
-/** Run async mutations with optional optimistic local updates and rollback. */
+/**
+ * Run async mutations with optional optimistic local updates and rollback.
+ *
+ * @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; use `useRequestSyncState()` instead.
+ */
 export function useOptimisticMutation<TVariables, TData, TSnapshot = unknown>(
   options: UseOptimisticMutationOptions<TVariables, TData, TSnapshot>,
 ): UseOptimisticMutationReturn<TVariables, TData, TSnapshot> {
@@ -90,18 +95,3 @@ export function useOptimisticMutation<TVariables, TData, TSnapshot = unknown>(
     reset,
   }
 }
-
-function readErrorMessage(value: unknown): string {
-  if (value instanceof Error && value.message) return value.message
-  if (typeof value === 'string' && value.trim()) return value
-  if (
-    typeof value === 'object'
-    && value !== null
-    && 'message' in value
-    && typeof (value as { message?: unknown }).message === 'string'
-    && (value as { message: string }).message.trim()
-  ) {
-    return (value as { message: string }).message
-  }
-  return 'Request failed.'
-}

package/src/composables/usePluginClient.ts

@@ -1,8 +1,6 @@
 import {
   computed,
-  getCurrentInstance,
   onMounted,
-  onUnmounted,
   ref,
   shallowRef,
   watch,
@@ -17,6 +15,7 @@ import {
 import { usePlatformContext } from './usePlatformContext'
 import { useRequestSyncState } from './useRequestSyncState'
 import { useAuthStore } from '../stores/auth'
+import { PLUGIN_SECRET_FORMAT_KEY } from '../utils/pluginSecrets'
 import {
   currentExperimentFromContext,
   getInjectedPlatformContext,
@@ -28,6 +27,12 @@ import {
   pluginEndpointRequestParts,
   requestBodyFromPayload,
 } from './pluginEndpointBuilder'
+import {
+  useEventStream,
+  type EventStreamMessage,
+  type EventStreamTransport,
+  type UseEventStreamReturn,
+} from './useEventStream'
 import type {
   ExperimentSummary,
   GeneratedJobDefinition,
@@ -204,13 +209,7 @@ export interface UsePluginSettingsReturn<TSettings = Record<string, unknown>> {
   reset: () => void
 }
 
-export interface PluginEventStreamMessage<TData = string> {
-  event: string
-  data: TData
-  id?: string
-  retry?: number
-  raw: string
-}
+export type PluginEventStreamMessage<TData = string> = EventStreamMessage<TData>
 
 export interface PluginEventStreamOptions<TData = string> {
   /** Override the generated or platform-injected API base URL. */
@@ -232,15 +231,7 @@ export interface PluginEventStreamOptions<TData = string> {
   onError?: (error: unknown) => void
 }
 
-export interface UsePluginEventStreamReturn<TData = string> {
-  isConnected: Ref<boolean>
-  isConnecting: Ref<boolean>
-  error: Ref<string | null>
-  lastMessage: Ref<PluginEventStreamMessage<TData> | null>
-  lastEventId: Ref<string | null>
-  start: () => void
-  stop: () => void
-}
+export type UsePluginEventStreamReturn<TData = string> = UseEventStreamReturn<TData>
 
 export type PluginFormDataValue =
   | string
@@ -544,16 +535,36 @@ export async function downloadPluginEndpoint(
   return blob
 }
 
-/** Return a generated plugin client from setup code with a stable typed identity. */
+function normalizePluginSettingsOptions(options: UsePluginSettingsOptions | string = {}): UsePluginSettingsOptions {
+  return typeof options === 'string' ? { pluginName: options } : options
+}
+
+/** @deprecated Use `useGeneratedPluginClient()` for generated clients. */
 export function usePluginClient<TClient>(client: TClient): TClient {
   return client
 }
 
-function normalizePluginSettingsOptions(options: UsePluginSettingsOptions | string = {}): UsePluginSettingsOptions {
-  return typeof options === 'string' ? { pluginName: options } : options
+const PLATFORM_OWNED_SETTINGS_KEY = 'allowed_experiment_types'
+
+/**
+ * Secret settings travel as `{ "$secret": "<id>" }` references, so an untouched
+ * secret round-trips without ever exposing its value. Declaring the format on
+ * every write keeps a `null` unambiguous: it clears the stored secret instead of
+ * meaning "unchanged", which is what the deprecated placeholder form meant.
+ */
+function withSecretFormat(
+  payload: Record<string, unknown>,
+  secretFormat: string | null,
+): Record<string, unknown> {
+  if (!secretFormat) return payload
+  return { ...payload, [PLUGIN_SECRET_FORMAT_KEY]: secretFormat }
 }
 
-const PLATFORM_OWNED_SETTINGS_KEY = 'allowed_experiment_types'
+function responseSecretFormat(response: unknown): string | null {
+  if (!response || typeof response !== 'object') return null
+  const format = (response as Record<string, unknown>)[PLUGIN_SECRET_FORMAT_KEY]
+  return typeof format === 'string' && format ? format : null
+}
 
 function cloneRecord(value: Record<string, unknown>): Record<string, unknown> {
   return JSON.parse(JSON.stringify(value)) as Record<string, unknown>
@@ -628,6 +639,7 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
   const values = ref({}) as Ref<PluginSettingsValues<TSettings>>
   const savedValues = shallowRef<Record<string, unknown>>({})
   const revision = ref<string | null>(null)
+  const secretFormat = ref<string | null>(null)
   const request = useRequestSyncState('Plugin settings request failed.')
   const isLoading = ref(false)
   const isSaving = ref(false)
@@ -660,11 +672,16 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
     values.value = cloneRecord(nextValues) as PluginSettingsValues<TSettings>
   }
 
-  function applyLoaded(nextValues: Record<string, unknown>, nextRevision: string | null): void {
+  function applyLoaded(
+    nextValues: Record<string, unknown>,
+    nextRevision: string | null,
+    nextSecretFormat: string | null = secretFormat.value,
+  ): void {
     const cloned = cloneRecord(nextValues)
     values.value = cloned as PluginSettingsValues<TSettings>
     savedValues.value = cloneRecord(cloned)
     revision.value = nextRevision
+    secretFormat.value = nextSecretFormat
   }
 
   async function load(): Promise<void> {
@@ -684,6 +701,7 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
       applyLoaded(
         responseSettingsPayload(response),
         responseSettingsRevision(response),
+        responseSecretFormat(response),
       )
     } catch {
       // Error state is handled by request.run().
@@ -717,7 +735,12 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
               revision?: string
             }>(
               `/plugins/${encodeURIComponent(resolvedPluginName.value)}/config`,
-              { config: topLevelSettingsPatch(payload, typedKeys) },
+              {
+                config: withSecretFormat(
+                  topLevelSettingsPatch(payload, typedKeys),
+                  secretFormat.value,
+                ),
+              },
             ),
             { success: 'save', errorMessage: 'Failed to save plugin settings' },
           )
@@ -740,7 +763,11 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
         }
 
         if (!response) return true
-        applyLoaded(responseSettingsPayload(response), nextRevision)
+        applyLoaded(
+          responseSettingsPayload(response),
+          nextRevision,
+          responseSecretFormat(response) ?? secretFormat.value,
+        )
         return true
       } else {
         const ifMatch = revision.value
@@ -751,13 +778,14 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
             settings: Record<string, unknown>
             mode?: string
             revision?: string
-          }>('/settings', payload, ifMatch),
+          }>('/settings', withSecretFormat(payload, secretFormat.value), ifMatch),
           { success: 'save', errorMessage: 'Failed to save plugin settings' },
         )
       }
       applyLoaded(
         responseSettingsPayload(response),
         responseSettingsRevision(response) ?? revision.value,
+        responseSecretFormat(response) ?? secretFormat.value,
       )
       return true
     } catch {
@@ -797,13 +825,13 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
 }
 
 function streamRequestAuth(
-  options: PluginEventStreamOptions<unknown>,
+  requestHeaders: HeadersInit | undefined,
   policy: { requiresAuth: boolean },
 ): {
   headers: Headers
   token?: string
 } {
-  const headers = new Headers(options.headers)
+  const headers = new Headers(requestHeaders)
   const authStore = useAuthStore()
   if (!authStore.isInitialized) {
     authStore.initialize()
@@ -811,7 +839,6 @@ function streamRequestAuth(
   if (policy.requiresAuth && authStore.token && !headers.has('Authorization')) {
     headers.set('Authorization', `Bearer ${authStore.token}`)
   }
-  headers.set('Accept', 'text/event-stream')
   const token = policy.requiresAuth ? authStore.token : undefined
   return {
     headers,
@@ -819,40 +846,22 @@ function streamRequestAuth(
   }
 }
 
-function parseSseEvent<TData>(
-  block: string,
-  parseJson: boolean,
-): PluginEventStreamMessage<TData> | null {
-  let event = 'message'
-  let id: string | undefined
-  let retry: number | undefined
-  const dataLines: string[] = []
-
-  for (const line of block.split(/\r?\n/)) {
-    if (!line || line.startsWith(':')) continue
-    const separator = line.indexOf(':')
-    const field = separator === -1 ? line : line.slice(0, separator)
-    const value = separator === -1
-      ? ''
-      : line.slice(separator + 1).replace(/^ /, '')
-
-    if (field === 'event') event = value || 'message'
-    if (field === 'data') dataLines.push(value)
-    if (field === 'id') id = value
-    if (field === 'retry') {
-      const parsed = Number(value)
-      if (Number.isFinite(parsed)) retry = parsed
+function pluginEventStreamTransport(
+  endpoint: PluginEndpointDefinition,
+): EventStreamTransport {
+  return async (url, init = {}) => {
+    if (typeof fetch !== 'function') {
+      throw new Error('[MINT SDK] fetch is required for plugin event streams.')
     }
-  }
-
-  if (!dataLines.length && !id && retry === undefined) return null
-  const data = dataLines.join('\n')
-  return {
-    event,
-    data: (parseJson && data ? JSON.parse(data) : data) as TData,
-    id,
-    retry,
-    raw: block,
+    const requestAuth = streamRequestAuth(
+      init.headers,
+      { requiresAuth: endpoint.requiresAuth !== false },
+    )
+    const response = await fetch(url, { ...init, headers: requestAuth.headers })
+    if (response.status === 401) {
+      throw authenticationRequiredError(response, requestAuth.token)
+    }
+    return response
   }
 }
 
@@ -891,6 +900,9 @@ export function usePluginEventStream<TData = string>(
   payloadOrOptions?: unknown,
   maybeOptions?: PluginEventStreamOptions<TData>,
 ): UsePluginEventStreamReturn<TData> {
+  if (endpoint.method !== 'get') {
+    throw new Error(`[MINT SDK] Plugin event streams must use GET; got ${endpoint.method}`)
+  }
   const payload = maybeOptions === undefined && looksLikeEventStreamOptions(payloadOrOptions)
     ? undefined
     : payloadOrOptions
@@ -899,198 +911,25 @@ export function usePluginEventStream<TData = string>(
       ? payloadOrOptions
       : maybeOptions ?? {}
   ) as PluginEventStreamOptions<TData>
-  const isConnected = ref(false)
-  const isConnecting = ref(false)
-  const error = ref<string | null>(null)
-  const lastMessage = shallowRef<PluginEventStreamMessage<TData> | null>(null)
-  const lastEventId = ref<string | null>(null)
   const responseType = endpoint.responseType?.trim()
   const parseJson = options.parseJson ?? Boolean(responseType && responseType !== 'string')
-  let controller: AbortController | null = null
-  let reconnectTimer: ReturnType<typeof setTimeout> | null = null
-  let stopped = true
-  let generation = 0
-
-  function clearReconnectTimer(): void {
-    if (reconnectTimer !== null) {
-      clearTimeout(reconnectTimer)
-      reconnectTimer = null
-    }
-  }
-
-  function ownsConnection(
-    connectionGeneration: number,
-    connectionController: AbortController,
-  ): boolean {
-    return !stopped
-      && generation === connectionGeneration
-      && controller === connectionController
-  }
-
-  function scheduleReconnect(connectionGeneration: number): void {
-    if (
-      stopped
-      || generation !== connectionGeneration
-      || options.reconnect === false
-    ) return
-    clearReconnectTimer()
-    reconnectTimer = setTimeout(() => {
-      reconnectTimer = null
-      if (stopped || generation !== connectionGeneration) return
-      void connect(connectionGeneration)
-    }, options.reconnectDelayMs ?? 2000)
-  }
-
-  async function connect(connectionGeneration: number): Promise<void> {
-    if (stopped || generation !== connectionGeneration) return
-    if (endpoint.method !== 'get') {
-      throw new Error(`[MINT SDK] Plugin event streams must use GET; got ${endpoint.method}`)
-    }
-    if (typeof fetch !== 'function') {
-      throw new Error('[MINT SDK] fetch is required for plugin event streams.')
-    }
-
-    controller?.abort()
-    const connectionController = new AbortController()
-    controller = connectionController
-    isConnecting.value = true
-    if (!ownsConnection(connectionGeneration, connectionController)) return
-    error.value = null
-    if (!ownsConnection(connectionGeneration, connectionController)) return
-
-    let authenticationFailed = false
-    try {
-      const url = buildPluginEndpointUrl(contract, endpoint, payload, {
-        baseUrl: options.baseUrl,
-      })
-      const requestAuth = streamRequestAuth(
-        options as PluginEventStreamOptions<unknown>,
-        { requiresAuth: endpoint.requiresAuth !== false },
-      )
-      const response = await fetch(url, {
-        method: 'GET',
-        headers: requestAuth.headers,
-        credentials: options.credentials ?? 'same-origin',
-        signal: connectionController.signal,
-      })
-
-      if (!ownsConnection(connectionGeneration, connectionController)) return
-
-      if (!response.ok) {
-        if (response.status === 401) {
-          authenticationFailed = true
-          throw authenticationRequiredError(response, requestAuth.token)
-        }
-        throw new Error(`Plugin event stream failed with HTTP ${response.status}`)
-      }
-      if (!response.body) {
-        throw new Error('Plugin event stream response did not include a readable body.')
-      }
-
-      isConnected.value = true
-      if (!ownsConnection(connectionGeneration, connectionController)) return
-      options.onOpen?.()
-      if (!ownsConnection(connectionGeneration, connectionController)) return
-      const reader = response.body.getReader()
-      const decoder = new TextDecoder()
-      let buffer = ''
-
-      for (;;) {
-        const { value, done } = await reader.read()
-        if (!ownsConnection(connectionGeneration, connectionController)) return
-        if (done) break
-        buffer += decoder.decode(value, { stream: true })
-
-        let boundary = buffer.search(/\r?\n\r?\n/)
-        while (boundary !== -1) {
-          const block = buffer.slice(0, boundary)
-          buffer = buffer.slice(buffer[boundary] === '\r' ? boundary + 4 : boundary + 2)
-          const message = parseSseEvent<TData>(block, parseJson)
-          if (message) {
-            lastMessage.value = message
-            if (!ownsConnection(connectionGeneration, connectionController)) return
-            if (message.id !== undefined) {
-              lastEventId.value = message.id
-              if (!ownsConnection(connectionGeneration, connectionController)) return
-            }
-            if (message.retry !== undefined) {
-              options.reconnectDelayMs = message.retry
-            }
-            if (!ownsConnection(connectionGeneration, connectionController)) return
-            options.onMessage?.(message)
-            if (!ownsConnection(connectionGeneration, connectionController)) return
-          }
-          boundary = buffer.search(/\r?\n\r?\n/)
-        }
-      }
-    } catch (err) {
-      if (err instanceof AuthenticationRequiredError) authenticationFailed = true
-      if (
-        ownsConnection(connectionGeneration, connectionController)
-        && !(err instanceof DOMException && err.name === 'AbortError')
-      ) {
-        const message = err instanceof Error ? err.message : 'Plugin event stream failed'
-        error.value = message
-        if (ownsConnection(connectionGeneration, connectionController)) {
-          options.onError?.(err)
-        }
-      }
-    } finally {
-      if (ownsConnection(connectionGeneration, connectionController)) {
-        isConnecting.value = false
-        if (ownsConnection(connectionGeneration, connectionController)) {
-          isConnected.value = false
-          if (ownsConnection(connectionGeneration, connectionController)) {
-            controller = null
-            if (authenticationFailed) {
-              stopped = true
-            } else {
-              scheduleReconnect(connectionGeneration)
-            }
-          }
-        }
-      }
-    }
-  }
-
-  function start(): void {
-    if (!stopped) return
-    stopped = false
-    clearReconnectTimer()
-    generation += 1
-    void connect(generation)
-  }
-
-  function stop(): void {
-    if (stopped) return
-    stopped = true
-    generation += 1
-    clearReconnectTimer()
-    controller?.abort()
-    controller = null
-    isConnecting.value = false
-    isConnected.value = false
-  }
-
-  const currentInstance = getCurrentInstance()
-  if (currentInstance && options.immediate !== false && typeof window === 'undefined') {
-    onMounted(start)
-  }
-  if (currentInstance) onUnmounted(stop)
-
-  if (options.immediate !== false && (typeof window !== 'undefined' || !currentInstance)) {
-    start()
-  }
-
-  return {
-    isConnected,
-    isConnecting,
-    error,
-    lastMessage,
-    lastEventId,
-    start,
-    stop,
-  }
+  return useEventStream<TData>(
+    () => buildPluginEndpointUrl(contract, endpoint, payload, { baseUrl: options.baseUrl }),
+    {
+      transport: pluginEventStreamTransport(endpoint),
+      immediate: options.immediate,
+      reconnect: options.reconnect,
+      reconnectDelayMs: options.reconnectDelayMs,
+      parseJson,
+      credentials: options.credentials,
+      headers: options.headers,
+      shouldReconnect: cause => !(cause instanceof AuthenticationRequiredError),
+      onOpen: options.onOpen,
+      onMessage: options.onMessage,
+      onError: options.onError,
+      errorLabel: 'Plugin event stream',
+    },
+  )
 }
 
 /** Read and optionally load the current platform experiment for integrated plugin views. */

package/src/composables/usePluginConfig.ts

@@ -75,7 +75,9 @@ export interface UsePluginConfigReturn {
   reset: () => void
 }
 
-/** Loads, saves, and tracks dirty state for a plugin's persistent configuration via the platform API. */
+/**
+ * @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; use `usePluginSettings()` for typed plugin settings.
+ */
 export function usePluginConfig(pluginName?: string): UsePluginConfigReturn {
   const injectedContext = getInjectedPlatformContext()
   const { plugin } = usePlatformContext()