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

package/package.json

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

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

@@ -57,6 +57,7 @@ describe('useAuth', () => {
         passkey_enabled: true,
         passkey_registered: false,
         registration_enabled: true,
+        database_mode: 'postgresql',
         access: { experiment_visibility_mode: 'restricted' },
       },
     })
@@ -67,6 +68,7 @@ describe('useAuth', () => {
       passkeyEnabled: true,
       passkeyRegistered: false,
       registrationEnabled: true,
+      databaseMode: 'postgresql',
       experimentVisibilityMode: 'restricted',
     }
 

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

@@ -0,0 +1,497 @@
+/**
+ * Tests for usePluginConfig.
+ *
+ * Covers the plugin settings life-cycle used by every plugin's
+ * settings pane:
+ *
+ * - resolvedName prefers explicit pluginName, falls back to platform plugin
+ * - load() populates config + savedConfig from /plugins/{name}/config
+ * - save() PATCHes the endpoint, updates savedConfig, returns true
+ * - isDirty reflects user edits vs last saved state
+ * - reset() restores config to savedConfig and clears error
+ * - lastLoadedAt / lastSavedAt track successful syncs
+ * - error messages bubble up from network failures
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createPinia, setActivePinia } from 'pinia'
+import axios, { type AxiosRequestConfig } from 'axios'
+import { nextTick } from 'vue'
+
+// usePluginConfig calls onMounted(load); happy-dom doesn't run Vue's
+// lifecycle outside a component, so we stub onMounted to call the
+// callback synchronously if and only if the test opts in.
+let autoLoadOnMount = false
+vi.mock('vue', async () => {
+  const actual = await vi.importActual<typeof import('vue')>('vue')
+  return {
+    ...actual,
+    onMounted: vi.fn((cb: () => void) => {
+      if (autoLoadOnMount) cb()
+    }),
+  }
+})
+
+import { usePluginConfig } from '../../composables/usePluginConfig'
+
+type FakeResponse = Record<string, unknown>
+
+let getResponse: FakeResponse = { plugin_name: 'drp', config: {} }
+let patchResponse: FakeResponse = { plugin_name: 'drp', config: {} }
+let putResponse: FakeResponse = { plugin_name: 'drp', config: {} }
+let getError: Error | null = null
+let patchError: Error | null = null
+let recordedBaseUrls: Array<string | undefined> = []
+let recordedCalls: {
+  method: string
+  url: string
+  data?: unknown
+  headers?: AxiosRequestConfig['headers']
+}[] = []
+
+function mockAxios() {
+  vi.spyOn(axios.Axios.prototype, 'get').mockImplementation(async function (
+    this: unknown,
+    url: string,
+    config?: AxiosRequestConfig,
+  ) {
+    recordedBaseUrls.push(config?.baseURL)
+    recordedCalls.push({ method: 'GET', url })
+    if (getError) throw getError
+    return { data: getResponse }
+  })
+  vi.spyOn(axios.Axios.prototype, 'patch').mockImplementation(async function (
+    this: unknown,
+    url: string,
+    data?: unknown,
+    config?: AxiosRequestConfig,
+  ) {
+    recordedBaseUrls.push(config?.baseURL)
+    recordedCalls.push({ method: 'PATCH', url, data })
+    if (patchError) throw patchError
+    return { data: patchResponse }
+  })
+  vi.spyOn(axios.Axios.prototype, 'put').mockImplementation(async function (
+    this: unknown,
+    url: string,
+    data?: unknown,
+    config?: AxiosRequestConfig,
+  ) {
+    recordedBaseUrls.push(config?.baseURL)
+    recordedCalls.push({ method: 'PUT', url, data, headers: config?.headers })
+    return { data: putResponse }
+  })
+}
+
+describe('usePluginConfig', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    autoLoadOnMount = false
+    getResponse = { plugin_name: 'drp', config: {} }
+    patchResponse = { plugin_name: 'drp', config: {} }
+    putResponse = { plugin_name: 'drp', config: {} }
+    getError = null
+    patchError = null
+    recordedCalls = []
+    recordedBaseUrls = []
+    delete (window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__
+    mockAxios()
+  })
+
+  afterEach(() => {
+    delete (window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__
+    vi.restoreAllMocks()
+  })
+
+  it('load fetches config from correct endpoint and populates state', async () => {
+    getResponse = {
+      plugin_name: 'drp',
+      config: { raw_files_path: '/data/rfa', threshold: 0.5 },
+    }
+    const hook = usePluginConfig('drp')
+    await hook.load()
+
+    expect(recordedCalls).toEqual([
+      { method: 'GET', url: '/plugins/drp/config' },
+    ])
+    expect(hook.config.value).toEqual({
+      raw_files_path: '/data/rfa',
+      threshold: 0.5,
+    })
+    expect(hook.isDirty.value).toBe(false)
+    expect(hook.error.value).toBeNull()
+    expect(hook.lastLoadedAt.value).toBeInstanceOf(Date)
+  })
+
+  it('encodes special characters in plugin name', async () => {
+    const hook = usePluginConfig('my/plugin')
+    await hook.load()
+    expect(recordedCalls[0]!.url).toBe('/plugins/my%2Fplugin/config')
+  })
+
+  it.each([
+    'platform',
+    undefined,
+  ] as const)(
+    'should use the platform config facade when settings_api is %s',
+    async (settingsApi) => {
+      ;(window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__ = {
+        isIntegrated: true,
+        theme: 'light',
+        platformApiUrl: '/api',
+        plugin: {
+          id: 'drp',
+          name: 'drp',
+          version: '1.0.0',
+          route_prefix: '/drp',
+          api_prefix: '/api/drp',
+          ...(settingsApi ? { settings_api: settingsApi } : {}),
+        },
+      }
+      getResponse = {
+        plugin_name: 'drp',
+        config: { n: 1 },
+        revision: 'revision-1',
+      }
+      const hook = usePluginConfig('drp')
+
+      await hook.load()
+
+      expect(recordedCalls).toEqual([
+        { method: 'GET', url: '/plugins/drp/config' },
+      ])
+    },
+  )
+
+  it('should use the plugin settings router for an integrated plugin capability', async () => {
+    ;(window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__ = {
+      isIntegrated: true,
+      theme: 'light',
+      platformApiUrl: '/api',
+      plugin: {
+        id: 'drp',
+        name: 'drp',
+        version: '1.0.0',
+        route_prefix: '/drp',
+        api_prefix: '/api/drp',
+        settings_api: 'plugin',
+      },
+    }
+    getResponse = {
+      settings: { n: 1 },
+      mode: 'integrated',
+      revision: 'revision-1',
+    }
+    putResponse = {
+      settings: { n: 2 },
+      mode: 'integrated',
+      revision: 'revision-2',
+    }
+    const hook = usePluginConfig('drp')
+    await hook.load()
+    hook.config.value = { n: 2 }
+
+    const saved = await hook.save()
+
+    expect({
+      saved,
+      calls: recordedCalls,
+      baseUrls: recordedBaseUrls,
+      config: hook.config.value,
+    }).toEqual({
+      saved: true,
+      baseUrls: ['/api/drp', '/api/drp'],
+      calls: [
+        { method: 'GET', url: '/settings' },
+        {
+          method: 'PUT',
+          url: '/settings',
+          data: { n: 2 },
+          headers: { 'If-Match': '"revision-1"' },
+        },
+      ],
+      config: { n: 2 },
+    })
+  })
+
+  it('should use the platform facade for an explicit different plugin name', async () => {
+    ;(window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__ = {
+      isIntegrated: true,
+      theme: 'light',
+      platformApiUrl: '/api',
+      plugin: {
+        id: 'current-plugin',
+        name: 'current-plugin',
+        version: '1.0.0',
+        route_prefix: '/current-plugin',
+        api_prefix: '/api/current-plugin',
+        settings_api: 'plugin',
+      },
+    }
+    getResponse = {
+      plugin_name: 'other-plugin',
+      config: { n: 1 },
+      revision: 'revision-1',
+    }
+
+    const hook = usePluginConfig('other-plugin')
+    await hook.load()
+
+    expect({
+      calls: recordedCalls,
+      config: hook.config.value,
+    }).toEqual({
+      calls: [
+        { method: 'GET', url: '/plugins/other-plugin/config' },
+      ],
+      config: { n: 1 },
+    })
+  })
+
+  it('should PATCH only dirty typed fields through a versioned platform facade', async () => {
+    getResponse = {
+      plugin_name: 'drp',
+      config: {
+        n: 1,
+        allowed_experiment_types: ['metabolomics'],
+      },
+      revision: 'revision-1',
+    }
+    patchResponse = {
+      plugin_name: 'drp',
+      config: {
+        n: 2,
+        allowed_experiment_types: ['metabolomics'],
+      },
+      revision: 'revision-2',
+    }
+    const hook = usePluginConfig('drp')
+    await hook.load()
+    hook.config.value = {
+      n: 2,
+      allowed_experiment_types: ['metabolomics'],
+    }
+    await nextTick()
+    expect(hook.isDirty.value).toBe(true)
+
+    const ok = await hook.save()
+    expect(ok).toBe(true)
+    const patchCall = recordedCalls.find((c) => c.method === 'PATCH')!
+    expect(patchCall.url).toBe('/plugins/drp/config')
+    expect(patchCall.data).toEqual({ config: { n: 2 } })
+    expect(patchCall.headers).toBeUndefined()
+    expect(hook.config.value).toEqual({
+      n: 2,
+      allowed_experiment_types: ['metabolomics'],
+    })
+    expect(hook.isDirty.value).toBe(false)
+    expect(hook.lastSavedAt.value).toBeInstanceOf(Date)
+  })
+
+  it('should split changed platform-owned config from a versioned typed save', async () => {
+    getResponse = {
+      plugin_name: 'drp',
+      config: {
+        n: 1,
+        allowed_experiment_types: ['metabolomics'],
+      },
+      revision: 'revision-1',
+    }
+    patchResponse = {
+      plugin_name: 'drp',
+      config: {
+        n: 2,
+        allowed_experiment_types: ['proteomics'],
+      },
+      revision: 'untrusted-platform-revision',
+    }
+    const hook = usePluginConfig('drp')
+    await hook.load()
+    hook.config.value = {
+      n: 2,
+      allowed_experiment_types: ['proteomics'],
+    }
+
+    const saved = await hook.save()
+    patchResponse = {
+      plugin_name: 'drp',
+      config: {
+        n: 3,
+        allowed_experiment_types: ['proteomics'],
+      },
+      revision: 'revision-3',
+    }
+    hook.config.value = {
+      n: 3,
+      allowed_experiment_types: ['proteomics'],
+    }
+    const savedAgain = await hook.save()
+
+    expect({
+      saved,
+      savedAgain,
+      calls: recordedCalls,
+      config: hook.config.value,
+      isDirty: hook.isDirty.value,
+    }).toEqual({
+      saved: true,
+      savedAgain: true,
+      calls: [
+        { method: 'GET', url: '/plugins/drp/config' },
+        {
+          method: 'PATCH',
+          url: '/plugins/drp/config',
+          data: { config: { n: 2 } },
+        },
+        {
+          method: 'PATCH',
+          url: '/plugins/drp/config',
+          data: { config: { allowed_experiment_types: ['proteomics'] } },
+        },
+        {
+          method: 'PATCH',
+          url: '/plugins/drp/config',
+          data: { config: { n: 3 } },
+        },
+      ],
+      config: {
+        n: 3,
+        allowed_experiment_types: ['proteomics'],
+      },
+      isDirty: false,
+    })
+  })
+
+  it('should avoid a typed PUT when only the platform-owned config changes', async () => {
+    getResponse = {
+      plugin_name: 'drp',
+      config: {
+        n: 1,
+        allowed_experiment_types: ['metabolomics'],
+      },
+      revision: 'revision-1',
+    }
+    patchResponse = {
+      plugin_name: 'drp',
+      config: {
+        n: 1,
+        allowed_experiment_types: ['proteomics'],
+      },
+    }
+    const hook = usePluginConfig('drp')
+    await hook.load()
+    hook.config.value = {
+      n: 1,
+      allowed_experiment_types: ['proteomics'],
+    }
+
+    const saved = await hook.save()
+
+    expect({
+      saved,
+      calls: recordedCalls,
+      config: hook.config.value,
+    }).toEqual({
+      saved: true,
+      calls: [
+        { method: 'GET', url: '/plugins/drp/config' },
+        {
+          method: 'PATCH',
+          url: '/plugins/drp/config',
+          data: { config: { allowed_experiment_types: ['proteomics'] } },
+        },
+      ],
+      config: {
+        n: 1,
+        allowed_experiment_types: ['proteomics'],
+      },
+    })
+  })
+
+  it('should detect nested config edits and restore the saved JSON snapshot', async () => {
+    getResponse = {
+      plugin_name: 'drp',
+      config: {
+        rules: {
+          thresholds: [1, 2],
+        },
+      },
+    }
+    const hook = usePluginConfig('drp')
+    await hook.load()
+    const rules = hook.config.value.rules as { thresholds: number[] }
+    rules.thresholds[0] = 9
+    await nextTick()
+
+    const dirtyAfterMutation = hook.isDirty.value
+    hook.reset()
+
+    expect({
+      dirtyAfterMutation,
+      config: hook.config.value,
+      isDirty: hook.isDirty.value,
+    }).toEqual({
+      dirtyAfterMutation: true,
+      config: {
+        rules: {
+          thresholds: [1, 2],
+        },
+      },
+      isDirty: false,
+    })
+  })
+
+  it('isDirty reflects edits vs last saved snapshot', async () => {
+    getResponse = { plugin_name: 'drp', config: { k: 'v' } }
+    const hook = usePluginConfig('drp')
+    await hook.load()
+    expect(hook.isDirty.value).toBe(false)
+
+    hook.config.value = { k: 'changed' }
+    await nextTick()
+    expect(hook.isDirty.value).toBe(true)
+
+    hook.config.value = { k: 'v' }
+    await nextTick()
+    expect(hook.isDirty.value).toBe(false)
+  })
+
+  it('reset restores saved config and clears error', async () => {
+    getResponse = { plugin_name: 'drp', config: { k: 'v' } }
+    const hook = usePluginConfig('drp')
+    await hook.load()
+    hook.config.value = { k: 'edited' }
+    hook.error.value = 'something'
+
+    hook.reset()
+    expect(hook.config.value).toEqual({ k: 'v' })
+    expect(hook.error.value).toBeNull()
+  })
+
+  it('load surfaces network error message', async () => {
+    getError = new Error('network down')
+    const hook = usePluginConfig('drp')
+    await hook.load()
+    expect(hook.error.value).toBe('network down')
+    expect(hook.isLoading.value).toBe(false)
+    expect(hook.lastLoadedAt.value).toBeNull()
+  })
+
+  it('save returns false and records error on failure', async () => {
+    patchError = new Error('403')
+    const hook = usePluginConfig('drp')
+    await hook.load()
+    hook.config.value = { x: 1 }
+    const ok = await hook.save()
+    expect(ok).toBe(false)
+    expect(hook.error.value).toBe('403')
+    expect(hook.lastSavedAt.value).toBeNull()
+  })
+
+  it('empty plugin name produces a noop load', async () => {
+    const hook = usePluginConfig('')
+    await hook.load()
+    expect(recordedCalls).toEqual([])
+    expect(hook.error.value).toBeNull()
+  })
+})

package/src/__tests__/docs/frontendDocsCatalog.test.ts

@@ -271,11 +271,14 @@ describe('frontend docs catalog coverage', () => {
     })
   })
 
-  it('documents only the source-driven JobsStatusTray props', () => {
+  it('documents the source and MINT 1.1 JobsStatusTray props', () => {
     const manifest = extractFrontendManifest()
     const jobsStatusTray = manifest.categories.components.find(item => item.name === 'JobsStatusTray')
 
     expect(jobsStatusTray?.props?.map(prop => prop.name).sort()).toEqual([
+      'adapter',
+      'eventStream',
+      'jobs',
       'loadOnMount',
       'source',
       'teleportTo',
@@ -319,6 +322,18 @@ describe('frontend docs catalog coverage', () => {
       'AppPillNav',
       'usePluginApi',
       'UsePluginApiOptions',
+    ]
+
+    for (const name of retiredNames) {
+      expect(rootIndex).not.toMatch(new RegExp(`\\b${name}\\b`))
+      expect(componentsIndex).not.toMatch(new RegExp(`\\b${name}\\b`))
+      expect(composableExports).not.toMatch(new RegExp(`\\b${name}\\b`))
+    }
+  })
+
+  it('keeps the MINT 1.1 composable compatibility exports', () => {
+    const composablesIndex = readFileSync(join(SDK_ROOT, 'src', 'composables', 'index.ts'), 'utf8')
+    const expected = [
       'useJobsStatusTray',
       'UseJobsStatusTrayOptions',
       'UseJobsStatusTrayReturn',
@@ -329,11 +344,7 @@ describe('frontend docs catalog coverage', () => {
       'usePluginClient',
     ]
 
-    for (const name of retiredNames) {
-      expect(rootIndex).not.toMatch(new RegExp(`\\b${name}\\b`))
-      expect(componentsIndex).not.toMatch(new RegExp(`\\b${name}\\b`))
-      expect(composableExports).not.toMatch(new RegExp(`\\b${name}\\b`))
-    }
+    expect(expected.filter(name => !new RegExp(`\\b${name}\\b`).test(composablesIndex))).toEqual([])
   })
 
   it('documents every public composable/helper export used by docs and doctor', () => {

package/src/components/JobsStatusTray.vue

@@ -15,12 +15,24 @@ import {
 } from '../jobs'
 import {
   usePluginJobCenter,
+  type JobsStatusTrayAdapter,
   type PluginJobCenterSource,
 } from '../composables/useJobsStatusTray'
-import type { JobState } from '../types/jobs'
+import type { UsePluginEventStreamReturn } from '../composables/usePluginClient'
+import type {
+  JobState,
+  JobStateInput,
+  JobStreamData,
+} from '../types/jobs'
 
 interface Props {
   source?: PluginJobCenterSource
+  /** @deprecated Pass a source instead. */
+  jobs?: readonly JobStateInput[]
+  /** @deprecated Pass source actions instead. */
+  adapter?: JobsStatusTrayAdapter
+  /** @deprecated Event streams belong to the source runtime. */
+  eventStream?: UsePluginEventStreamReturn<JobStreamData>
   loadOnMount?: boolean
   title?: string
   teleportTo?: string | HTMLElement | false
@@ -49,6 +61,9 @@ const panelRef = ref<HTMLElement | null>(null)
 const teleportTarget = computed(() => props.teleportTo || 'body')
 const tray = usePluginJobCenter({
   source: toRef(props, 'source'),
+  jobs: toRef(props, 'jobs'),
+  adapter: toRef(props, 'adapter'),
+  eventStream: toRef(props, 'eventStream'),
   loadOnMount: props.loadOnMount,
 })
 const canClear = computed(() => (

package/src/composables/index.ts

@@ -153,6 +153,7 @@ export {
   type UseGeneratedAnalysisReturn,
 } from './useGeneratedAnalysis'
 export { useAutoGroup, DEFAULT_COLORS, extractSamplesFromDesignData } from './useAutoGroup'
+export { usePluginConfig, type UsePluginConfigReturn } from './usePluginConfig'
 export {
   useReagentSeries,
   generateDilutionSeries,
@@ -487,6 +488,7 @@ export {
   pluginFormDataFromPayload,
   resolvePluginBaseUrl,
   uploadPluginEndpoint,
+  usePluginClient,
   usePluginEventStream,
   usePluginSettings,
   useCurrentExperiment,
@@ -515,9 +517,14 @@ export {
 export {
   combinePluginJobSources,
   usePluginJobCenter,
+  useJobsStatusTray,
   type CombinedPluginJobCenterSource,
+  type JobsStatusTrayAdapter,
+  type JobStreamMessage,
   type PluginJobCenterSource,
   type JobsStatusTrayTab,
+  type UseJobsStatusTrayOptions,
+  type UseJobsStatusTrayReturn,
   type UsePluginJobCenterOptions,
   type UsePluginJobCenterReturn,
 } from './useJobsStatusTray'

package/src/composables/useAuth.ts

@@ -93,6 +93,7 @@ export function useAuth(): UseAuthReturn {
         passkey_enabled: boolean
         passkey_registered?: boolean
         registration_enabled?: boolean
+        database_mode?: string
         access?: {
           experiment_visibility_mode?: 'open' | 'restricted'
           experimentVisibilityMode?: 'open' | 'restricted'
@@ -104,6 +105,7 @@ export function useAuth(): UseAuthReturn {
         passkeyEnabled: response.data.passkey_enabled,
         passkeyRegistered: response.data.passkey_registered ?? false,
         registrationEnabled: response.data.registration_enabled ?? false,
+        databaseMode: response.data.database_mode ?? 'none',
         experimentVisibilityMode:
           response.data.access?.experiment_visibility_mode
           ?? response.data.access?.experimentVisibilityMode
@@ -119,6 +121,7 @@ export function useAuth(): UseAuthReturn {
         passkeyEnabled: false,
         passkeyRegistered: false,
         registrationEnabled: false,
+        databaseMode: 'none',
         experimentVisibilityMode: 'open',
       }
     }

package/src/composables/useGeneratedAnalysis.ts

@@ -8,7 +8,10 @@ import {
   type ShallowRef,
 } from 'vue'
 
-import type { PluginJobCenterSource } from './useJobsStatusTray'
+import type {
+  JobsStatusTrayAdapter,
+  PluginJobCenterSource,
+} from './useJobsStatusTray'
 import { useEventStream, type EventStreamMessage } from './useEventStream'
 import { normalizeJobState } from '../jobs'
 import type {
@@ -102,6 +105,8 @@ export interface UsePluginJobsReturn extends PluginJobCenterSource {
   pause: () => void
   resume: () => void
   dispose: () => void
+  /** @deprecated Pass the runtime itself to SDK job UI as its source. */
+  jobsAdapter: JobsStatusTrayAdapter
 }
 
 export type UseGeneratedAnalysisReturn = UsePluginJobsReturn
@@ -972,6 +977,13 @@ function createPluginJobs(
     return payload.deleted
   }
 
+  const jobsAdapter: JobsStatusTrayAdapter = {
+    listJobs: async () => ({ jobs: await refreshJobs() }),
+    cancelJob: async job => cancelJob(job as GeneratedAnalysisJob),
+    deleteJob: async job => deleteJob(job as GeneratedAnalysisJob),
+    clearFinishedJobs: async () => clearFinishedJobs(),
+  }
+
   function pause(): void {
     if (disposed || paused) return
     paused = true
@@ -1065,6 +1077,7 @@ function createPluginJobs(
     pause,
     resume,
     dispose,
+    jobsAdapter,
   }
 }