@morscherlab/mint-sdk 1.2.0-beta.1 → 1.2.0-beta.3

package/src/composables/usePluginClient.ts

@@ -1,963 +0,0 @@
-import {
-  computed,
-  onMounted,
-  ref,
-  shallowRef,
-  watch,
-  type ComputedRef,
-  type Ref,
-} from 'vue'
-import {
-  AuthenticationRequiredError,
-  authenticationRequiredError,
-  useApi,
-} from './useApi'
-import { usePlatformContext } from './usePlatformContext'
-import { useRequestSyncState } from './useRequestSyncState'
-import { useAuthStore } from '../stores/auth'
-import {
-  currentExperimentFromContext,
-  getInjectedPlatformContext,
-  resolveCurrentExperimentId,
-} from './platformContextHelpers'
-import {
-  buildPluginEndpointUrl,
-  hasKeys,
-  pluginEndpointRequestParts,
-  requestBodyFromPayload,
-} from './pluginEndpointBuilder'
-import {
-  useEventStream,
-  type EventStreamMessage,
-  type EventStreamTransport,
-  type UseEventStreamReturn,
-} from './useEventStream'
-import type {
-  ExperimentSummary,
-  GeneratedJobDefinition,
-  PageSelectorItem,
-  SettingsModalSchema,
-  TopBarSettingsConfig,
-} from '../types'
-
-export {
-  buildPluginEndpointUrl,
-  resolvePluginBaseUrl,
-} from './pluginEndpointBuilder'
-
-export type PluginHttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete'
-
-export interface PluginEndpointContract {
-  name: string
-  operationId?: string
-  method: PluginHttpMethod
-  path: string
-  requiresAuth?: boolean
-  pathParams?: PluginEndpointParamContract[]
-  queryParams?: PluginEndpointParamContract[]
-  requestType?: string | null
-  requestContentType?: string | null
-  responseType?: string | null
-  responseContentType?: string | null
-  eventStream?: boolean
-}
-
-export interface PluginEndpointParamContract {
-  name: string
-  fieldName: string
-  type?: string
-  required?: boolean
-}
-
-export interface PluginNavItemContract {
-  path: string
-  label: string
-  id?: string
-  icon?: string
-  description?: string
-  requiresAuth?: boolean
-  requiresAdmin?: boolean
-  requiresFeature?: string
-}
-
-export interface PluginContractSettings {
-  modelName: string | null
-  /** Pydantic JSON Schema used to generate typed settings values. */
-  valueSchema: Record<string, unknown> | null
-  /** SDK SettingsModal schema used to render the settings form. */
-  formSchema: SettingsModalSchema | null
-}
-
-export interface PluginContract {
-  schemaVersion: 2
-  plugin: {
-    name?: string
-    packageName?: string
-    version?: string
-    description?: string
-    routesPrefix: string
-    apiPrefix: string
-    type: 'analysis' | 'experiment-design' | string
-    analysisType?: string
-    icon?: string
-    color?: string
-    navItems?: PluginNavItemContract[]
-    analysisResultReaders?: string[]
-    capabilities?: Record<string, unknown>
-  }
-  settings: PluginContractSettings
-  endpoints: PluginEndpointContract[]
-  schemas?: Record<string, Record<string, unknown>>
-  jobs?: GeneratedJobDefinition[]
-  hash: string
-}
-
-export interface PluginEndpointDefinition {
-  method: PluginHttpMethod
-  path: string
-  requiresAuth?: boolean
-  pathParams?: PluginEndpointParamDefinition[]
-  queryParams?: PluginEndpointParamDefinition[]
-  hasBody?: boolean
-  requestContentType?: string | null
-  eventStream?: boolean
-  responseType?: string | null
-  responseContentType?: string | null
-}
-
-export type PluginEndpointParamDefinition = string | {
-  name: string
-  fieldName?: string
-  type?: string
-  required?: boolean
-}
-
-export interface CreatePluginClientOptions {
-  endpoints: Record<string, PluginEndpointDefinition>
-  baseUrl?: string
-}
-
-export interface BuildPluginEndpointUrlOptions {
-  /** Override the generated or platform-injected API base URL. */
-  baseUrl?: string
-  /** Return only the endpoint path and query string instead of base URL + path. */
-  includeBaseUrl?: boolean
-}
-
-export interface PluginEndpointRequestOptions {
-  /** Override the generated or platform-injected API base URL. */
-  baseUrl?: string
-  /** Cancel the request without changing its endpoint or authentication behavior. */
-  signal?: AbortSignal
-}
-
-export interface PluginClientRequestOptions {
-  /** Cancel the generated endpoint request. */
-  signal?: AbortSignal
-}
-
-export interface DownloadPluginEndpointOptions extends PluginEndpointRequestOptions {
-  /** Browser download filename. When omitted, the blob is returned without triggering a download. */
-  filename?: string
-  /** Delay before revoking the object URL after a browser download is triggered. */
-  revokeObjectUrlDelayMs?: number
-}
-
-export interface DownloadBlobOptions {
-  /** Delay before revoking the object URL after a browser download is triggered. */
-  revokeObjectUrlDelayMs?: number
-}
-
-export type PluginSettingsValues<TSettings> = Partial<TSettings> & Record<string, unknown>
-
-export interface UsePluginSettingsOptions {
-  /** Plugin name for platform persistence. Defaults to the integrated platform plugin name. */
-  pluginName?: string
-  /** Plugin API base URL for standalone/local settings routes. Generated clients pass pluginApiPrefix. */
-  apiBaseUrl?: string
-  /** Platform API base URL for /plugins/{name}/config. Defaults to the injected platform API URL. */
-  platformApiBaseUrl?: string
-  /** SettingsModal schema generated from the backend plugin config model. */
-  schema?: SettingsModalSchema | null
-  /** SettingsModal title when using settingsConfig. */
-  title?: string
-  /** Whether SettingsModal should include SDK appearance controls. */
-  showAppearance?: boolean
-  /** Load persisted values on component mount. */
-  loadOnMount?: boolean
-}
-
-export interface UsePluginSettingsReturn<TSettings = Record<string, unknown>> {
-  /** Current typed settings values. */
-  settings: ComputedRef<PluginSettingsValues<TSettings>>
-  /** Editable settings values for SettingsModal. */
-  values: Ref<PluginSettingsValues<TSettings>>
-  /** Alias for values, kept for callers that think in platform config terms. */
-  config: Ref<PluginSettingsValues<TSettings>>
-  /** Ready-to-pass AppTopBar/PluginWorkspaceView settingsConfig. */
-  settingsConfig: ComputedRef<TopBarSettingsConfig>
-  isLoading: Ref<boolean>
-  isSaving: Ref<boolean>
-  error: Ref<string | null>
-  lastLoadedAt: Ref<Date | null>
-  lastSavedAt: Ref<Date | null>
-  isDirty: ComputedRef<boolean>
-  setValues: (values: Record<string, unknown>) => void
-  load: () => Promise<void>
-  save: (values?: Record<string, unknown>) => Promise<boolean>
-  reset: () => void
-}
-
-export type PluginEventStreamMessage<TData = string> = EventStreamMessage<TData>
-
-export interface PluginEventStreamOptions<TData = string> {
-  /** Override the generated or platform-injected API base URL. */
-  baseUrl?: string
-  /** Start the stream immediately. Defaults to true. */
-  immediate?: boolean
-  /** Reconnect after errors or server closes. Defaults to true. */
-  reconnect?: boolean
-  /** Delay before reconnecting after a stream failure or close. Defaults to 2000ms. */
-  reconnectDelayMs?: number
-  /** Parse `data:` as JSON. Defaults to true for typed endpoints and false otherwise. */
-  parseJson?: boolean
-  /** Fetch credentials mode. Defaults to same-origin. */
-  credentials?: RequestCredentials
-  /** Extra request headers. Authorization is injected unless already supplied. */
-  headers?: Record<string, string>
-  onOpen?: () => void
-  onMessage?: (message: PluginEventStreamMessage<TData>) => void
-  onError?: (error: unknown) => void
-}
-
-export type UsePluginEventStreamReturn<TData = string> = UseEventStreamReturn<TData>
-
-export type PluginFormDataValue =
-  | string
-  | number
-  | boolean
-  | Blob
-  | null
-  | undefined
-  | Record<string, unknown>
-
-export type PluginFormDataPayload = Record<string, PluginFormDataValue | PluginFormDataValue[]>
-
-export interface UseCurrentExperimentOptions {
-  apiBaseUrl?: string
-  immediate?: boolean
-}
-
-export interface UseCurrentExperimentReturn<TExperiment = ExperimentSummary> {
-  /** Current experiment id resolved from platform injection or URL conventions. */
-  experimentId: ComputedRef<number | undefined>
-  /** Whether a current experiment id is available. */
-  hasExperiment: ComputedRef<boolean>
-  /** Current experiment payload, if injected or successfully fetched. */
-  experiment: Ref<TExperiment | undefined>
-  /** Whether the current experiment is currently loading. */
-  isLoading: Ref<boolean>
-  /** Error message from the last failed current-experiment fetch, or null. */
-  error: Ref<string | null>
-  /** Timestamp of the last successful current-experiment fetch, or null. */
-  lastLoadedAt: Ref<Date | null>
-  /** Return the current experiment id or throw a clear SDK error when absent. */
-  requireExperimentId: () => number
-  /** Fetch a specific experiment id, defaulting to the current experiment id. */
-  fetch: (experimentId?: number) => Promise<TExperiment | undefined>
-  /** Refetch the currently resolved experiment id. */
-  refresh: () => Promise<TExperiment | undefined>
-}
-
-export type PluginEndpointCaller = (
-  payloadOrOptions?: unknown,
-  options?: PluginClientRequestOptions,
-) => Promise<unknown>
-export type GeneratedPluginClient = Record<string, (...args: any[]) => Promise<any>>
-
-function queryConfig(query: Record<string, unknown>) {
-  return hasKeys(query) ? { params: query } : undefined
-}
-
-const OCTET_STREAM = 'application/octet-stream'
-const MULTIPART_FORM_DATA = 'multipart/form-data'
-
-function endpointRequestConfig(
-  endpoint: PluginEndpointDefinition,
-  query: Record<string, unknown>,
-  options?: PluginClientRequestOptions,
-) {
-  const config: Record<string, unknown> = {}
-  if (hasKeys(query)) config.params = query
-  if (endpoint.requestContentType === OCTET_STREAM) {
-    config.headers = { 'Content-Type': OCTET_STREAM }
-  }
-  if (endpoint.requestContentType === MULTIPART_FORM_DATA) {
-    config.headers = { 'Content-Type': undefined }
-  }
-  if (endpoint.responseContentType === OCTET_STREAM) {
-    config.responseType = 'blob'
-  }
-  if (options?.signal) config.signal = options.signal
-  return hasKeys(config) ? config : undefined
-}
-
-function isFormData(value: unknown): value is FormData {
-  return typeof FormData !== 'undefined' && value instanceof FormData
-}
-
-function endpointRequestBody(endpoint: PluginEndpointDefinition, body: unknown): unknown {
-  return endpoint.requestContentType === MULTIPART_FORM_DATA
-    ? pluginFormDataFromPayload(body)
-    : body
-}
-
-function endpointHasPayload(endpoint: PluginEndpointDefinition): boolean {
-  return Boolean(
-    endpoint.hasBody
-    || endpoint.pathParams?.length
-    || endpoint.queryParams?.length,
-  )
-}
-
-function isBlob(value: unknown): value is Blob {
-  return typeof Blob !== 'undefined' && value instanceof Blob
-}
-
-function appendFormDataValue(formData: FormData, key: string, value: PluginFormDataValue | PluginFormDataValue[]): void {
-  if (value === undefined || value === null) return
-
-  if (Array.isArray(value)) {
-    for (const item of value) {
-      appendFormDataValue(formData, key, item)
-    }
-    return
-  }
-
-  if (isBlob(value)) {
-    formData.append(key, value)
-    return
-  }
-
-  if (typeof value === 'object') {
-    formData.append(key, JSON.stringify(value))
-    return
-  }
-
-  formData.append(key, String(value))
-}
-
-/** Convert plain upload payloads into FormData using the same encoding across generated plugin clients. */
-export function pluginFormDataFromPayload(payload: unknown): FormData {
-  if (isFormData(payload)) return payload
-  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
-    throw new Error('[MINT SDK] Plugin upload endpoints require a FormData or plain object payload.')
-  }
-
-  const formData = new FormData()
-  for (const [key, value] of Object.entries(payload as PluginFormDataPayload)) {
-    appendFormDataValue(formData, key, value)
-  }
-  return formData
-}
-
-/** Trigger a browser download for an already-created Blob. */
-export function downloadBlob(blob: Blob, filename: string, options: DownloadBlobOptions = {}): void {
-  if (typeof document === 'undefined' || typeof URL === 'undefined') {
-    throw new Error('[MINT SDK] Cannot trigger a file download outside a browser.')
-  }
-
-  const blobUrl = URL.createObjectURL(blob)
-  const link = document.createElement('a')
-  link.href = blobUrl
-  link.download = filename
-  document.body.appendChild(link)
-  link.click()
-  document.body.removeChild(link)
-  setTimeout(() => URL.revokeObjectURL(blobUrl), options.revokeObjectUrlDelayMs ?? 100)
-}
-
-function normalizePluginNavPath(path: string): string {
-  const raw = path.trim() || '/'
-  const prefixed = raw.startsWith('/') ? raw : `/${raw}`
-  return prefixed.replace(/\/+$/, '') || '/'
-}
-
-function pluginPageIdFromPath(path: string, fallbackIndex: number): string {
-  const normalizedPath = normalizePluginNavPath(path)
-  if (normalizedPath === '/') return 'dashboard'
-  return normalizedPath.replace(/^\/+/, '').replace(/\/+/g, '-') || `page-${fallbackIndex + 1}`
-}
-
-/** Convert resolved @mint_plugin nav_items into page selectors for the topbar and homepage PluginCards. */
-export function getPluginPageSelectorItems(contract: PluginContract): PageSelectorItem[] {
-  const pluginIcon = contract.plugin.icon ?? ''
-  const navItems = contract.plugin.navItems ?? []
-  return navItems.map((item, index) => ({
-    id: item.id || pluginPageIdFromPath(item.path, index),
-    label: item.label,
-    to: normalizePluginNavPath(item.path),
-    icon: item.icon || pluginIcon || undefined,
-  }))
-}
-
-/** Create a typed plugin API client from a generated MINT plugin contract. */
-export function createPluginClient<TClient extends object = GeneratedPluginClient>(
-  contract: PluginContract,
-  options: CreatePluginClientOptions,
-): TClient {
-  const client: Record<string, PluginEndpointCaller> = {}
-
-  for (const [name, endpoint] of Object.entries(options.endpoints)) {
-    client[name] = async (
-      payloadOrOptions?: unknown,
-      explicitOptions?: PluginClientRequestOptions,
-    ) => {
-      const hasPayload = endpointHasPayload(endpoint)
-      const payload = hasPayload ? payloadOrOptions : undefined
-      const callOptions = hasPayload
-        ? explicitOptions
-        : (payloadOrOptions as PluginClientRequestOptions | undefined) ?? explicitOptions
-      const parts = pluginEndpointRequestParts(contract, endpoint, payload, options.baseUrl)
-      const api = useApi({
-        baseUrl: parts.baseUrl,
-        withAuth: endpoint.requiresAuth !== false,
-      })
-      const config = endpointRequestConfig(endpoint, parts.query, callOptions)
-
-      if (endpoint.method === 'get') {
-        return api.get(parts.path, config)
-      }
-
-      if (endpoint.method === 'delete') {
-        const rawBody = requestBodyFromPayload(payload, parts.requestPayload, endpoint)
-        const body = rawBody === undefined ? undefined : endpointRequestBody(endpoint, rawBody)
-        const config = body === undefined
-          ? endpointRequestConfig(endpoint, parts.query, callOptions)
-          : { ...endpointRequestConfig(endpoint, parts.query, callOptions), data: body }
-        return api.delete(parts.path, config)
-      }
-
-      const body = endpointRequestBody(
-        endpoint,
-        requestBodyFromPayload(payload, parts.requestPayload, endpoint),
-      )
-
-      if (endpoint.method === 'post') return api.post(parts.path, body, config)
-      if (endpoint.method === 'put') return api.put(parts.path, body, config)
-      if (endpoint.method === 'patch') return api.patch(parts.path, body, config)
-      throw new Error(`[MINT SDK] Unsupported plugin endpoint method: ${endpoint.method}`)
-    }
-  }
-
-  return client as TClient
-}
-
-/** Send multipart or raw binary data to a generated endpoint with contract URL, cancellation, and auth handling. */
-export async function uploadPluginEndpoint<TResponse = unknown>(
-  contract: PluginContract,
-  endpoint: PluginEndpointDefinition,
-  payload?: unknown,
-  options: PluginEndpointRequestOptions = {},
-): Promise<TResponse> {
-  if (!['post', 'put', 'patch'].includes(endpoint.method)) {
-    throw new Error(`[MINT SDK] Plugin upload endpoints must use POST, PUT, or PATCH; got ${endpoint.method}`)
-  }
-
-  const parts = pluginEndpointRequestParts(contract, endpoint, payload, options.baseUrl)
-  const api = useApi({
-    baseUrl: parts.baseUrl,
-    withAuth: endpoint.requiresAuth !== false,
-  })
-  const body = endpoint.hasBody
-    ? requestBodyFromPayload(payload, parts.requestPayload, endpoint)
-    : payload
-  if (endpoint.requestContentType === OCTET_STREAM) {
-    const config = endpointRequestConfig(endpoint, parts.query, { signal: options.signal })
-    if (endpoint.method === 'post') return api.post<TResponse>(parts.path, body, config)
-    if (endpoint.method === 'put') return api.put<TResponse>(parts.path, body, config)
-    return api.patch<TResponse>(parts.path, body, config)
-  }
-  const formData = pluginFormDataFromPayload(body)
-  const config = {
-    ...(queryConfig(parts.query) ?? {}),
-    ...(options.signal ? { signal: options.signal } : {}),
-    // Let Axios/browser set multipart boundaries.
-    headers: { 'Content-Type': undefined },
-  }
-
-  if (endpoint.method === 'post') return api.post<TResponse>(parts.path, formData, config)
-  if (endpoint.method === 'put') return api.put<TResponse>(parts.path, formData, config)
-  return api.patch<TResponse>(parts.path, formData, config)
-}
-
-/** Fetch a generated plugin endpoint as a Blob and optionally trigger a browser download. */
-export async function downloadPluginEndpoint(
-  contract: PluginContract,
-  endpoint: PluginEndpointDefinition,
-  payload?: unknown,
-  options: DownloadPluginEndpointOptions = {},
-): Promise<Blob> {
-  if (endpoint.requestContentType === MULTIPART_FORM_DATA) {
-    throw new Error('[MINT SDK] Plugin download endpoints do not support multipart request bodies')
-  }
-
-  const parts = pluginEndpointRequestParts(contract, endpoint, payload, options.baseUrl)
-  const api = useApi({
-    baseUrl: parts.baseUrl,
-    withAuth: endpoint.requiresAuth !== false,
-  })
-  const config = {
-    ...(endpointRequestConfig(endpoint, parts.query, { signal: options.signal }) ?? {}),
-    responseType: 'blob' as const,
-  }
-  const rawBody = requestBodyFromPayload(payload, parts.requestPayload, endpoint)
-  const body = rawBody === undefined ? undefined : endpointRequestBody(endpoint, rawBody)
-  let blob: Blob
-
-  if (endpoint.method === 'get') blob = await api.get<Blob>(parts.path, config)
-  else if (endpoint.method === 'post') blob = await api.post<Blob>(parts.path, body, config)
-  else if (endpoint.method === 'put') blob = await api.put<Blob>(parts.path, body, config)
-  else if (endpoint.method === 'patch') blob = await api.patch<Blob>(parts.path, body, config)
-  else if (endpoint.method === 'delete') {
-    blob = await api.delete<Blob>(parts.path, body === undefined ? config : { ...config, data: body })
-  } else {
-    throw new Error(`[MINT SDK] Unsupported plugin endpoint method: ${endpoint.method}`)
-  }
-
-  if (options.filename) {
-    downloadBlob(blob, options.filename, {
-      revokeObjectUrlDelayMs: options.revokeObjectUrlDelayMs,
-    })
-  }
-
-  return blob
-}
-
-function normalizePluginSettingsOptions(options: UsePluginSettingsOptions | string = {}): UsePluginSettingsOptions {
-  return typeof options === 'string' ? { pluginName: options } : options
-}
-
-const PLATFORM_OWNED_SETTINGS_KEY = 'allowed_experiment_types'
-
-function cloneRecord(value: Record<string, unknown>): Record<string, unknown> {
-  return JSON.parse(JSON.stringify(value)) as Record<string, unknown>
-}
-
-function hasOwnSetting(settings: Record<string, unknown>, key: string): boolean {
-  return Object.prototype.hasOwnProperty.call(settings, key)
-}
-
-function responseSettingsPayload(response: unknown): Record<string, unknown> {
-  if (!response || typeof response !== 'object') return {}
-  const data = response as {
-    config?: unknown
-    settings?: unknown
-  }
-  if (data.config && typeof data.config === 'object') {
-    return cloneRecord(data.config as Record<string, unknown>)
-  }
-  if (data.settings && typeof data.settings === 'object') {
-    return cloneRecord(data.settings as Record<string, unknown>)
-  }
-  return {}
-}
-
-function responseSettingsRevision(response: unknown): string | null {
-  if (!response || typeof response !== 'object') return null
-  const revision = (response as { revision?: unknown }).revision
-  return typeof revision === 'string' && revision ? revision : null
-}
-
-function topLevelSettingsPatch(
-  current: Record<string, unknown>,
-  keys: Iterable<string>,
-): Record<string, unknown> {
-  return Object.fromEntries(
-    [...keys].map(key => [
-      key,
-      hasOwnSetting(current, key) ? current[key] : null,
-    ]),
-  )
-}
-
-function changedTopLevelSettingKeys(
-  current: Record<string, unknown>,
-  saved: Record<string, unknown>,
-): Set<string> {
-  return new Set(
-    [...new Set([...Object.keys(current), ...Object.keys(saved)])].filter(
-      key => JSON.stringify(current[key]) !== JSON.stringify(saved[key]),
-    ),
-  )
-}
-
-function platformOwnedSettingsPatch(settings: Record<string, unknown>): Record<string, unknown> {
-  return {
-    [PLATFORM_OWNED_SETTINGS_KEY]: hasOwnSetting(settings, PLATFORM_OWNED_SETTINGS_KEY)
-      ? settings[PLATFORM_OWNED_SETTINGS_KEY]
-      : null,
-  }
-}
-
-/** Load, edit, and persist plugin settings from platform config or the plugin-local settings router. */
-export function usePluginSettings<TSettings = Record<string, unknown>>(
-  options: UsePluginSettingsOptions | string = {},
-): UsePluginSettingsReturn<TSettings> {
-  const resolvedOptions = normalizePluginSettingsOptions(options)
-  const injectedContext = getInjectedPlatformContext()
-  const { plugin, isIntegrated } = usePlatformContext()
-  const platformApi = useApi({ baseUrl: resolvedOptions.platformApiBaseUrl ?? injectedContext?.platformApiUrl })
-  const pluginApi = useApi({ baseUrl: resolvedOptions.apiBaseUrl ?? injectedContext?.plugin?.api_prefix })
-
-  const values = ref({}) as Ref<PluginSettingsValues<TSettings>>
-  const savedValues = shallowRef<Record<string, unknown>>({})
-  const revision = ref<string | null>(null)
-  const request = useRequestSyncState('Plugin settings request failed.')
-  const isLoading = ref(false)
-  const isSaving = ref(false)
-
-  const resolvedPluginName = computed(() =>
-    resolvedOptions.pluginName ?? plugin.value?.name ?? injectedContext?.plugin?.name ?? '',
-  )
-  const usesPluginSettingsApi = computed(() => {
-    const currentPlugin = injectedContext?.plugin ?? plugin.value
-    return currentPlugin?.settings_api === 'plugin'
-      && resolvedPluginName.value === currentPlugin.name
-  })
-  const usesPlatformConfig = computed(() =>
-    Boolean(
-      (isIntegrated.value || injectedContext?.isIntegrated)
-      && resolvedPluginName.value
-      && !usesPluginSettingsApi.value,
-    ),
-  )
-  const settings = computed(() => values.value)
-  const isDirty = computed(() => JSON.stringify(values.value) !== JSON.stringify(savedValues.value))
-  const settingsConfig = computed<TopBarSettingsConfig>(() => ({
-    title: resolvedOptions.title,
-    schema: resolvedOptions.schema ?? undefined,
-    showAppearance: resolvedOptions.showAppearance,
-    values: values.value,
-  }))
-
-  function setValues(nextValues: Record<string, unknown>): void {
-    values.value = cloneRecord(nextValues) as PluginSettingsValues<TSettings>
-  }
-
-  function applyLoaded(nextValues: Record<string, unknown>, nextRevision: string | null): void {
-    const cloned = cloneRecord(nextValues)
-    values.value = cloned as PluginSettingsValues<TSettings>
-    savedValues.value = cloneRecord(cloned)
-    revision.value = nextRevision
-  }
-
-  async function load(): Promise<void> {
-    isLoading.value = true
-    try {
-      const response = usesPlatformConfig.value
-        ? await request.run(
-          () => platformApi.get<{ plugin_name: string; config: Record<string, unknown> }>(
-            `/plugins/${encodeURIComponent(resolvedPluginName.value)}/config`,
-          ),
-          { success: 'load', errorMessage: 'Failed to load plugin settings' },
-        )
-        : await request.run(
-          () => pluginApi.get<{ settings: Record<string, unknown>; mode?: string }>('/settings'),
-          { success: 'load', errorMessage: 'Failed to load plugin settings' },
-        )
-      applyLoaded(
-        responseSettingsPayload(response),
-        responseSettingsRevision(response),
-      )
-    } catch {
-      // Error state is handled by request.run().
-    } finally {
-      isLoading.value = false
-    }
-  }
-
-  async function save(nextValues?: Record<string, unknown>): Promise<boolean> {
-    if (nextValues) {
-      setValues(nextValues)
-    }
-
-    isSaving.value = true
-    try {
-      const payload = cloneRecord(values.value)
-      let response: unknown
-      if (usesPlatformConfig.value) {
-        const dirtyKeys = changedTopLevelSettingKeys(payload, savedValues.value)
-        const platformOwnedChanged = dirtyKeys.has(PLATFORM_OWNED_SETTINGS_KEY)
-        const typedKeys = [...dirtyKeys].filter(
-          key => key !== PLATFORM_OWNED_SETTINGS_KEY,
-        )
-        let nextRevision = revision.value
-
-        if (typedKeys.length) {
-          response = await request.run(
-            () => platformApi.patch<{
-              plugin_name: string
-              config: Record<string, unknown>
-              revision?: string
-            }>(
-              `/plugins/${encodeURIComponent(resolvedPluginName.value)}/config`,
-              { config: topLevelSettingsPatch(payload, typedKeys) },
-            ),
-            { success: 'save', errorMessage: 'Failed to save plugin settings' },
-          )
-          nextRevision = responseSettingsRevision(response) ?? nextRevision
-        }
-
-        if (platformOwnedChanged) {
-          response = await request.run(
-            () => platformApi.patch<{
-              plugin_name: string
-              config: Record<string, unknown>
-              revision?: string
-            }>(
-              `/plugins/${encodeURIComponent(resolvedPluginName.value)}/config`,
-              { config: platformOwnedSettingsPatch(payload) },
-            ),
-            { success: 'save', errorMessage: 'Failed to save plugin settings' },
-          )
-          nextRevision = responseSettingsRevision(response) ?? nextRevision
-        }
-
-        if (!response) return true
-        applyLoaded(responseSettingsPayload(response), nextRevision)
-        return true
-      } else {
-        const ifMatch = revision.value
-          ? { headers: { 'If-Match': `"${revision.value}"` } }
-          : undefined
-        response = await request.run(
-          () => pluginApi.put<{
-            settings: Record<string, unknown>
-            mode?: string
-            revision?: string
-          }>('/settings', payload, ifMatch),
-          { success: 'save', errorMessage: 'Failed to save plugin settings' },
-        )
-      }
-      applyLoaded(
-        responseSettingsPayload(response),
-        responseSettingsRevision(response) ?? revision.value,
-      )
-      return true
-    } catch {
-      return false
-    } finally {
-      isSaving.value = false
-    }
-  }
-
-  function reset(): void {
-    values.value = cloneRecord(savedValues.value) as PluginSettingsValues<TSettings>
-    request.clearError()
-  }
-
-  onMounted(() => {
-    if (resolvedOptions.loadOnMount !== false) {
-      void load()
-    }
-  })
-
-  return {
-    settings,
-    values,
-    config: values,
-    settingsConfig,
-    isLoading,
-    isSaving,
-    error: request.error,
-    lastLoadedAt: request.lastLoadedAt,
-    lastSavedAt: request.lastSavedAt,
-    isDirty,
-    setValues,
-    load,
-    save,
-    reset,
-  }
-}
-
-function streamRequestAuth(
-  requestHeaders: HeadersInit | undefined,
-  policy: { requiresAuth: boolean },
-): {
-  headers: Headers
-  token?: string
-} {
-  const headers = new Headers(requestHeaders)
-  const authStore = useAuthStore()
-  if (!authStore.isInitialized) {
-    authStore.initialize()
-  }
-  if (policy.requiresAuth && authStore.token && !headers.has('Authorization')) {
-    headers.set('Authorization', `Bearer ${authStore.token}`)
-  }
-  const token = policy.requiresAuth ? authStore.token : undefined
-  return {
-    headers,
-    token: token && headers.get('Authorization') === `Bearer ${token}` ? token : undefined,
-  }
-}
-
-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.')
-    }
-    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
-  }
-}
-
-function looksLikeEventStreamOptions(value: unknown): value is PluginEventStreamOptions {
-  if (!value || typeof value !== 'object') return false
-  const candidate = value as Record<string, unknown>
-  return [
-    'baseUrl',
-    'immediate',
-    'reconnect',
-    'reconnectDelayMs',
-    'parseJson',
-    'credentials',
-    'headers',
-    'onOpen',
-    'onMessage',
-    'onError',
-  ].some(key => key in candidate)
-}
-
-/** Consume a generated plugin SSE endpoint with auth headers, reconnect, and teardown. */
-export function usePluginEventStream<TData = string>(
-  contract: PluginContract,
-  endpoint: PluginEndpointDefinition,
-  options?: PluginEventStreamOptions<TData>,
-): UsePluginEventStreamReturn<TData>
-export function usePluginEventStream<TData = string>(
-  contract: PluginContract,
-  endpoint: PluginEndpointDefinition,
-  payload?: unknown,
-  options?: PluginEventStreamOptions<TData>,
-): UsePluginEventStreamReturn<TData>
-export function usePluginEventStream<TData = string>(
-  contract: PluginContract,
-  endpoint: PluginEndpointDefinition,
-  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
-  const options = (
-    maybeOptions === undefined && looksLikeEventStreamOptions(payloadOrOptions)
-      ? payloadOrOptions
-      : maybeOptions ?? {}
-  ) as PluginEventStreamOptions<TData>
-  const responseType = endpoint.responseType?.trim()
-  const parseJson = options.parseJson ?? Boolean(responseType && responseType !== 'string')
-  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. */
-export function useCurrentExperiment<TExperiment = ExperimentSummary>(
-  options: UseCurrentExperimentOptions = {},
-): UseCurrentExperimentReturn<TExperiment> {
-  const api = useApi({ baseUrl: options.apiBaseUrl ?? getInjectedPlatformContext()?.platformApiUrl })
-  const experiment = shallowRef<TExperiment | undefined>(currentExperimentFromContext<TExperiment>())
-  const request = useRequestSyncState('Failed to load current experiment')
-  const isLoading = request.loading
-  const error = request.error
-  const lastLoadedAt = request.lastLoadedAt
-
-  const experimentId = computed<number | undefined>(() => {
-    return resolveCurrentExperimentId()
-  })
-  const hasExperiment = computed(() => experimentId.value !== undefined)
-
-  function requireExperimentId(): number {
-    const id = experimentId.value
-    if (id === undefined) {
-      throw new Error('[MINT SDK] No current experiment is selected.')
-    }
-    return id
-  }
-
-  async function fetchExperiment(id = experimentId.value): Promise<TExperiment | undefined> {
-    if (id === undefined) {
-      experiment.value = currentExperimentFromContext<TExperiment>()
-      return experiment.value
-    }
-
-    try {
-      const result = await request.run(
-        () => api.get<TExperiment>(`/experiments/${id}`),
-        { success: 'load', errorMessage: 'Failed to load current experiment' },
-      )
-      experiment.value = result
-      return result
-    } catch (e) {
-      experiment.value = undefined
-      return undefined
-    }
-  }
-
-  async function refresh(): Promise<TExperiment | undefined> {
-    return fetchExperiment()
-  }
-
-  watch(
-    experimentId,
-    (id) => {
-      if (options.immediate === false) return
-      if (id === undefined) {
-        experiment.value = currentExperimentFromContext<TExperiment>()
-        return
-      }
-      void fetchExperiment(id)
-    },
-    { immediate: options.immediate !== false },
-  )
-
-  return {
-    experimentId,
-    hasExperiment,
-    experiment,
-    isLoading,
-    error,
-    lastLoadedAt,
-    requireExperimentId,
-    fetch: fetchExperiment,
-    refresh,
-  }
-}