@morscherlab/mint-sdk 1.0.0-beta.2 → 1.0.0-beta.4

package/src/composables/usePluginClient.ts

@@ -0,0 +1,466 @@
+import { computed, shallowRef, watch, type ComputedRef, type Ref } from 'vue'
+import { useApi } from './useApi'
+import { usePlatformContext } from './usePlatformContext'
+import { useRequestSyncState } from './useRequestSyncState'
+import {
+  currentExperimentFromContext,
+  getInjectedPlatformContext,
+  resolveCurrentExperimentId,
+} from './platformContextHelpers'
+import type { ExperimentSummary, PageSelectorItem } from '../types'
+
+export type PluginHttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete'
+
+export interface PluginEndpointContract {
+  name: string
+  method: PluginHttpMethod
+  path: string
+  pathParams?: string[]
+  queryParams?: PluginEndpointParamContract[]
+  requestType?: string | null
+  responseType?: string | null
+}
+
+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 PluginContract {
+  schemaVersion: number
+  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[]
+    capabilities?: Record<string, unknown>
+  }
+  endpoints: PluginEndpointContract[]
+  hash: string
+}
+
+export interface PluginEndpointDefinition {
+  method: PluginHttpMethod
+  path: string
+  pathParams?: string[]
+  queryParams?: PluginEndpointParamDefinition[]
+  hasBody?: boolean
+}
+
+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 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 = (payload?: unknown) => Promise<unknown>
+export type GeneratedPluginClient = Record<string, (...args: any[]) => Promise<any>>
+
+function normalizeApiBaseUrl(baseUrl: string | undefined): string | undefined {
+  if (!baseUrl) return undefined
+  return baseUrl.length > 1 ? baseUrl.replace(/\/+$/, '') : baseUrl
+}
+
+function normalizeApiPrefix(prefix: string | undefined): string | undefined {
+  if (!prefix) return undefined
+  if (prefix.startsWith('/api/')) return normalizeApiBaseUrl(prefix)
+  if (prefix === '/api') return prefix
+  if (prefix.startsWith('/')) return normalizeApiBaseUrl(`/api${prefix}`)
+  return normalizeApiBaseUrl(`/api/${prefix}`)
+}
+
+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 PluginMetadata.nav_items into AppTopBar pageSelector items for topbar page switches, homepage PluginCards, and fallback views. */
+export function getPluginPageSelectorItems(contract: PluginContract): PageSelectorItem[] {
+  const pluginIcon = contract.plugin.icon ?? ''
+  const navItems = contract.plugin.navItems ?? []
+  const source: PluginNavItemContract[] = navItems.length > 0
+    ? navItems
+    : [{
+        path: '/',
+        label: contract.plugin.name ?? 'Dashboard',
+        id: 'dashboard',
+        icon: pluginIcon || undefined,
+        description: contract.plugin.description,
+      }]
+
+  return source.map((item, index) => ({
+    id: item.id || pluginPageIdFromPath(item.path, index),
+    label: item.label,
+    to: normalizePluginNavPath(item.path),
+    icon: item.icon || pluginIcon || undefined,
+    hint: item.description || contract.plugin.name,
+  }))
+}
+
+/** Resolve the runtime plugin API base URL from env, explicit options, platform injection, or contract metadata. */
+export function resolvePluginBaseUrl(contract: PluginContract, explicitBaseUrl?: string): string {
+  const envPrefix = (import.meta.env?.VITE_API_PREFIX as string | undefined) || undefined
+  if (envPrefix) return normalizeApiBaseUrl(envPrefix) ?? envPrefix
+  if (explicitBaseUrl) return normalizeApiBaseUrl(explicitBaseUrl) ?? explicitBaseUrl
+
+  const injected = getInjectedPlatformContext()
+  const platformPrefix =
+    normalizeApiBaseUrl(injected?.plugin?.api_prefix) ||
+    normalizeApiPrefix(injected?.plugin?.route_prefix)
+  if (platformPrefix) return platformPrefix
+
+  return normalizeApiBaseUrl(contract.plugin.apiPrefix) || '/api'
+}
+
+function encodePath(path: string, payload: Record<string, unknown>, pathParams: string[]): string {
+  let nextPath = path
+  for (const param of pathParams) {
+    const value = payload[param]
+    if (value === undefined || value === null) {
+      throw new Error(`[MINT SDK] Missing path parameter '${param}' for plugin endpoint ${path}`)
+    }
+    nextPath = nextPath.replace(`{${param}}`, encodeURIComponent(String(value)))
+    nextPath = nextPath.replace(`:${param}`, encodeURIComponent(String(value)))
+  }
+  return nextPath
+}
+
+function withDefaultPathParams(
+  payload: Record<string, unknown>,
+  pathParams: string[],
+): Record<string, unknown> {
+  if (!pathParams.length) return payload
+  const nextPayload = { ...payload }
+  for (const param of pathParams) {
+    if (nextPayload[param] !== undefined && nextPayload[param] !== null) continue
+    if (isExperimentPathParam(param)) {
+      const experimentId = resolveCurrentExperimentId()
+      if (experimentId !== undefined) {
+        nextPayload[param] = experimentId
+      }
+    }
+  }
+  return nextPayload
+}
+
+function isExperimentPathParam(param: string): boolean {
+  return param === 'experimentId' || param === 'experiment_id'
+}
+
+function withoutPathParams(payload: Record<string, unknown>, pathParams: string[]) {
+  const copy = { ...payload }
+  for (const param of pathParams) {
+    delete copy[param]
+  }
+  return copy
+}
+
+function queryParamsFromPayload(
+  payload: Record<string, unknown>,
+  pathParams: string[],
+  queryParams?: PluginEndpointParamDefinition[],
+  endpointPath?: string,
+  includeUnspecifiedParams = false,
+) {
+  if (!queryParams?.length) {
+    return includeUnspecifiedParams ? withoutPathParams(payload, pathParams) : {}
+  }
+
+  const query: Record<string, unknown> = {}
+  for (const param of queryParams) {
+    const name = typeof param === 'string' ? param : param.name
+    const fieldName = typeof param === 'string' ? param : param.fieldName ?? param.name
+    const required = typeof param !== 'string' && param.required === true
+    const value = payload[fieldName]
+    if (value === undefined || value === null) {
+      if (required) {
+        throw new Error(
+          `[MINT SDK] Missing query parameter '${fieldName}' for plugin endpoint ${endpointPath ?? ''}`,
+        )
+      }
+      continue
+    }
+    query[name] = value
+  }
+  return query
+}
+
+function hasKeys(value: Record<string, unknown>): boolean {
+  return Object.keys(value).length > 0
+}
+
+function requestBodyFromPayload(
+  payload: unknown,
+  requestPayload: Record<string, unknown>,
+  endpoint: PluginEndpointDefinition,
+): unknown {
+  if (!endpoint.hasBody) return undefined
+  const body = endpoint.pathParams?.length || endpoint.queryParams?.length
+    ? requestPayload.body
+    : payload
+  if (body === undefined || body === null) {
+    throw new Error(`[MINT SDK] Missing request body for plugin endpoint ${endpoint.path}`)
+  }
+  return body
+}
+
+function pluginEndpointRequestParts(
+  contract: PluginContract,
+  endpoint: PluginEndpointDefinition,
+  payload?: unknown,
+  explicitBaseUrl?: string,
+) {
+  const payloadObject =
+    payload && typeof payload === 'object' && !Array.isArray(payload)
+      ? payload as Record<string, unknown>
+      : {}
+  const pathParams = endpoint.pathParams ?? []
+  const requestPayload = withDefaultPathParams(payloadObject, pathParams)
+  const path = encodePath(endpoint.path, requestPayload, pathParams)
+  const query = queryParamsFromPayload(
+    requestPayload,
+    pathParams,
+    endpoint.queryParams,
+    endpoint.path,
+    endpoint.method === 'get',
+  )
+
+  return {
+    baseUrl: resolvePluginBaseUrl(contract, explicitBaseUrl),
+    path,
+    query,
+    requestPayload,
+  }
+}
+
+function appendQueryValue(params: URLSearchParams, key: string, value: unknown): void {
+  if (value === undefined || value === null) return
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      appendQueryValue(params, key, item)
+    }
+    return
+  }
+  if (typeof value === 'object') {
+    params.append(key, JSON.stringify(value))
+    return
+  }
+  params.append(key, String(value))
+}
+
+function queryString(query: Record<string, unknown>): string {
+  const params = new URLSearchParams()
+  for (const [key, value] of Object.entries(query)) {
+    appendQueryValue(params, key, value)
+  }
+  const serialized = params.toString()
+  return serialized ? `?${serialized}` : ''
+}
+
+function joinBaseUrl(baseUrl: string, path: string): string {
+  if (!baseUrl) return path
+  const normalizedBase = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`
+  return `${normalizedBase}${normalizedPath}`
+}
+
+/** Build the concrete URL for a generated plugin endpoint without making a request. */
+export function buildPluginEndpointUrl(
+  contract: PluginContract,
+  endpoint: PluginEndpointDefinition,
+  payload?: unknown,
+  options: BuildPluginEndpointUrlOptions = {},
+): string {
+  const parts = pluginEndpointRequestParts(contract, endpoint, payload, options.baseUrl)
+  const pathWithQuery = `${parts.path}${queryString(parts.query)}`
+  if (options.includeBaseUrl === false) return pathWithQuery
+  return joinBaseUrl(parts.baseUrl, pathWithQuery)
+}
+
+/** 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 (payload?: unknown) => {
+      const parts = pluginEndpointRequestParts(contract, endpoint, payload, options.baseUrl)
+      const api = useApi({ baseUrl: parts.baseUrl })
+      const queryConfig = hasKeys(parts.query) ? { params: parts.query } : undefined
+
+      if (endpoint.method === 'get') {
+        return api.get(parts.path, queryConfig)
+      }
+
+      if (endpoint.method === 'delete') {
+        const body = requestBodyFromPayload(payload, parts.requestPayload, endpoint)
+        const config = body === undefined
+          ? queryConfig
+          : { ...queryConfig, data: body }
+        return api.delete(parts.path, config)
+      }
+
+      const body = requestBodyFromPayload(payload, parts.requestPayload, endpoint)
+
+      if (endpoint.method === 'post') return api.post(parts.path, body, queryConfig)
+      if (endpoint.method === 'put') return api.put(parts.path, body, queryConfig)
+      if (endpoint.method === 'patch') return api.patch(parts.path, body, queryConfig)
+      throw new Error(`[MINT SDK] Unsupported plugin endpoint method: ${endpoint.method}`)
+    }
+  }
+
+  return client as TClient
+}
+
+/** Return a generated plugin client from setup code with a stable typed identity. */
+export function usePluginClient<TClient>(client: TClient): TClient {
+  return client
+}
+
+/** Read plugin settings exposed through the platform context. */
+export function usePluginSettings<TSettings = Record<string, unknown>>() {
+  const { plugin } = usePlatformContext()
+  const settings = computed(() => plugin.value?.settings as TSettings | undefined)
+  return { settings }
+}
+
+/** 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,
+  }
+}

package/src/composables/usePluginConfig.ts

@@ -1,15 +1,28 @@
 import { ref, computed, onMounted, type Ref, type ComputedRef } from 'vue'
 import { useApi } from './useApi'
 import { usePlatformContext } from './usePlatformContext'
+import { useRequestSyncState } from './useRequestSyncState'
 
 export interface UsePluginConfigReturn {
+  /** Editable plugin configuration values. */
   config: Ref<Record<string, unknown>>
+  /** Whether the config is currently loading. */
   isLoading: Ref<boolean>
+  /** Whether the config is currently saving. */
   isSaving: Ref<boolean>
+  /** Error message from the last failed operation, or null. */
   error: Ref<string | null>
+  /** Timestamp of the last successful load, or null. */
+  lastLoadedAt: Ref<Date | null>
+  /** Timestamp of the last successful save, or null. */
+  lastSavedAt: Ref<Date | null>
+  /** Whether local config differs from the last loaded or saved snapshot. */
   isDirty: ComputedRef<boolean>
+  /** Load plugin configuration from the platform. */
   load: () => Promise<void>
+  /** Save plugin configuration to the platform. */
   save: () => Promise<boolean>
+  /** Restore the last loaded or saved configuration snapshot. */
   reset: () => void
 }
 
@@ -22,9 +35,12 @@ export function usePluginConfig(pluginName?: string): UsePluginConfigReturn {
 
   const config = ref<Record<string, unknown>>({})
   const savedConfig = ref<Record<string, unknown>>({})
+  const request = useRequestSyncState('Plugin config request failed.')
   const isLoading = ref(false)
   const isSaving = ref(false)
-  const error = ref<string | null>(null)
+  const error = request.error
+  const lastLoadedAt = request.lastLoadedAt
+  const lastSavedAt = request.lastSavedAt
 
   const isDirty = computed(() => {
     return JSON.stringify(config.value) !== JSON.stringify(savedConfig.value)
@@ -35,15 +51,17 @@ export function usePluginConfig(pluginName?: string): UsePluginConfigReturn {
     if (!name) return
 
     isLoading.value = true
-    error.value = null
     try {
-      const response = await api.get<{ plugin_name: string; config: Record<string, unknown> }>(
-        `/plugins/${encodeURIComponent(name)}/config`,
+      const response = await request.run(
+        () => api.get<{ plugin_name: string; config: Record<string, unknown> }>(
+          `/plugins/${encodeURIComponent(name)}/config`,
+        ),
+        { success: 'load', errorMessage: 'Failed to load plugin config' },
       )
       config.value = { ...response.config }
       savedConfig.value = { ...response.config }
-    } catch (e) {
-      error.value = e instanceof Error ? e.message : 'Failed to load plugin config'
+    } catch {
+      // Error state is handled by request.run().
     } finally {
       isLoading.value = false
     }
@@ -54,17 +72,18 @@ export function usePluginConfig(pluginName?: string): UsePluginConfigReturn {
     if (!name) return false
 
     isSaving.value = true
-    error.value = null
     try {
-      const response = await api.patch<{ plugin_name: string; config: Record<string, unknown> }>(
-        `/plugins/${encodeURIComponent(name)}/config`,
-        { config: config.value },
+      const response = await request.run(
+        () => api.patch<{ plugin_name: string; config: Record<string, unknown> }>(
+          `/plugins/${encodeURIComponent(name)}/config`,
+          { config: config.value },
+        ),
+        { success: 'save', errorMessage: 'Failed to save plugin config' },
       )
       config.value = { ...response.config }
       savedConfig.value = { ...response.config }
       return true
-    } catch (e) {
-      error.value = e instanceof Error ? e.message : 'Failed to save plugin config'
+    } catch {
       return false
     } finally {
       isSaving.value = false
@@ -73,7 +92,7 @@ export function usePluginConfig(pluginName?: string): UsePluginConfigReturn {
 
   function reset(): void {
     config.value = { ...savedConfig.value }
-    error.value = null
+    request.clearError()
   }
 
   onMounted(() => {
@@ -85,6 +104,8 @@ export function usePluginConfig(pluginName?: string): UsePluginConfigReturn {
     isLoading,
     isSaving,
     error,
+    lastLoadedAt,
+    lastSavedAt,
     isDirty,
     load,
     save,

package/src/composables/useRequestSyncState.ts

@@ -0,0 +1,126 @@
+import { ref, type Ref } from 'vue'
+
+export type RequestSyncSuccessKind = 'load' | 'save' | 'run'
+
+export interface RequestSyncRunOptions {
+  success?: RequestSyncSuccessKind
+  errorMessage?: string
+}
+
+export interface UseRequestSyncStateReturn {
+  /** Whether a request is in progress. */
+  loading: Ref<boolean>
+  /** Message from the last failed request, or null. */
+  error: Ref<string | null>
+  /** Timestamp of the last successful load operation, or null. */
+  lastLoadedAt: Ref<Date | null>
+  /** Timestamp of the last successful save operation, or null. */
+  lastSavedAt: Ref<Date | null>
+  /** Timestamp of the last successful run operation, or null. */
+  lastRunAt: Ref<Date | null>
+  /** Clear the current error without changing loading or timestamps. */
+  clearError: () => void
+  /** Convert thrown values into a developer-facing error message. */
+  readErrorMessage: (value: unknown, fallback?: string) => string
+  /** Store and return a normalized error message. */
+  setError: (value: unknown, fallback?: string) => string
+  /** Mark the resource as successfully loaded. */
+  markLoaded: (date?: Date) => void
+  /** Mark the resource as successfully saved. */
+  markSaved: (date?: Date) => void
+  /** Mark the operation as successfully run. */
+  markRun: (date?: Date) => void
+  /** Run a request with shared loading/error handling and optional sync marking. */
+  run: <T>(operation: () => Promise<T>, options?: RequestSyncRunOptions) => Promise<T>
+}
+
+/** Shared loading/error/timestamp state for generated plugin request helpers. */
+export function useRequestSyncState(
+  defaultErrorMessage = 'Request failed.',
+): UseRequestSyncStateReturn {
+  const loading = ref(false)
+  const error = ref<string | null>(null)
+  const lastLoadedAt = ref<Date | null>(null)
+  const lastSavedAt = ref<Date | null>(null)
+  const lastRunAt = ref<Date | null>(null)
+
+  function clearError(): void {
+    error.value = null
+  }
+
+  function readErrorMessage(value: unknown, fallback = defaultErrorMessage): 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
+    ) {
+      return (value as { message: string }).message
+    }
+    return fallback
+  }
+
+  function setError(value: unknown, fallback?: string): string {
+    const message = readErrorMessage(value, fallback)
+    error.value = message
+    return message
+  }
+
+  function markLoaded(date = new Date()): void {
+    lastLoadedAt.value = date
+  }
+
+  function markSaved(date = new Date()): void {
+    lastSavedAt.value = date
+  }
+
+  function markRun(date = new Date()): void {
+    lastRunAt.value = date
+  }
+
+  async function run<T>(
+    operation: () => Promise<T>,
+    options: RequestSyncRunOptions = {},
+  ): Promise<T> {
+    loading.value = true
+    clearError()
+    try {
+      const response = await operation()
+      if (options.success === 'load') {
+        markLoaded()
+      } else if (options.success === 'save') {
+        markSaved()
+      } else if (options.success === 'run') {
+        markRun()
+      }
+      return response
+    } catch (err) {
+      setError(err, options.errorMessage)
+      throw err
+    } finally {
+      loading.value = false
+    }
+  }
+
+  return {
+    loading,
+    error,
+    lastLoadedAt,
+    lastSavedAt,
+    lastRunAt,
+    clearError,
+    readErrorMessage,
+    setError,
+    markLoaded,
+    markSaved,
+    markRun,
+    run,
+  }
+}