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

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

@@ -0,0 +1,541 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createPinia, setActivePinia } from 'pinia'
+import axios, { type AxiosRequestConfig } from 'axios'
+
+import {
+  buildPluginEndpointUrl,
+  createPluginClient,
+  getPluginPageSelectorItems,
+  resolvePluginBaseUrl,
+  useCurrentExperiment,
+  usePluginClient,
+  type PluginContract,
+} from '../../composables/usePluginClient'
+
+const contract: PluginContract = {
+  schemaVersion: 1,
+  plugin: {
+    routesPrefix: '/drp',
+    apiPrefix: '/api/drp',
+    type: 'analysis',
+  },
+  endpoints: [],
+  hash: 'sha256:test',
+}
+
+describe('usePluginClient', () => {
+  let requestConfigs: AxiosRequestConfig[] = []
+  let requestBodies: unknown[] = []
+  let nextGetError: Error | null = null
+
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    requestConfigs = []
+    requestBodies = []
+    nextGetError = null
+    vi.spyOn(axios.Axios.prototype, 'get').mockImplementation(async function (
+      this: unknown,
+      url: string,
+      config?: AxiosRequestConfig,
+    ) {
+      requestConfigs.push({ url, ...config })
+      if (nextGetError) throw nextGetError
+      return { data: { called: url } }
+    })
+    vi.spyOn(axios.Axios.prototype, 'post').mockImplementation(async function (
+      this: unknown,
+      url: string,
+      data?: unknown,
+      config?: AxiosRequestConfig,
+    ) {
+      requestConfigs.push({ url, ...config })
+      requestBodies.push(data)
+      return { data: { called: url } }
+    })
+    vi.spyOn(axios.Axios.prototype, 'delete').mockImplementation(async function (
+      this: unknown,
+      url: string,
+      config?: AxiosRequestConfig,
+    ) {
+      requestConfigs.push({ url, ...config })
+      requestBodies.push(config?.data)
+      return { data: { called: url } }
+    })
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+    vi.unstubAllEnvs()
+    window.history.replaceState({}, '', '/')
+    delete (window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__
+  })
+
+  it('uses contract apiPrefix by default', async () => {
+    const client = createPluginClient(contract, {
+      endpoints: {
+        health: { method: 'get', path: '/health' },
+      },
+    })
+
+    await client.health()
+
+    expect(requestConfigs[0]!.baseURL).toBe('/api/drp')
+    expect(requestConfigs[0]!.url).toBe('/health')
+  })
+
+  it('VITE_API_PREFIX overrides contract apiPrefix', async () => {
+    vi.stubEnv('VITE_API_PREFIX', '/api/override')
+    const client = createPluginClient(contract, {
+      endpoints: {
+        health: { method: 'get', path: '/health' },
+      },
+    })
+
+    await client.health()
+
+    expect(requestConfigs[0]!.baseURL).toBe('/api/override')
+  })
+
+  it('platform injected api_prefix overrides contract fallback', async () => {
+    ;(window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__ = {
+      isIntegrated: true,
+      theme: 'light',
+      plugin: {
+        id: 'drp',
+        name: 'DRP',
+        version: '1.0.0',
+        route_prefix: '/drp',
+        api_prefix: '/api/platform-drp',
+      },
+    }
+    const client = createPluginClient(contract, {
+      endpoints: {
+        health: { method: 'get', path: '/health' },
+      },
+    })
+
+    await client.health()
+
+    expect(requestConfigs[0]!.baseURL).toBe('/api/platform-drp')
+  })
+
+  it('resolves plugin base URLs without making requests', () => {
+    expect(resolvePluginBaseUrl(contract)).toBe('/api/drp')
+
+    expect(resolvePluginBaseUrl(
+      { ...contract, plugin: { ...contract.plugin, apiPrefix: '/api/drp/' } },
+    )).toBe('/api/drp')
+    expect(resolvePluginBaseUrl(contract, '/api/explicit/')).toBe('/api/explicit')
+
+    vi.stubEnv('VITE_API_PREFIX', '/api/env/')
+    expect(resolvePluginBaseUrl(contract, '/api/explicit')).toBe('/api/env')
+  })
+
+  it('normalizes platform-injected plugin base URLs', () => {
+    ;(window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__ = {
+      isIntegrated: true,
+      theme: 'light',
+      plugin: {
+        id: 'drp',
+        name: 'DRP',
+        version: '1.0.0',
+        route_prefix: '/ignored/',
+        api_prefix: '/api/platform-drp/',
+      },
+    }
+
+    expect(resolvePluginBaseUrl(contract)).toBe('/api/platform-drp')
+
+    ;(window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__ = {
+      isIntegrated: true,
+      theme: 'light',
+      plugin: {
+        id: 'drp',
+        name: 'DRP',
+        version: '1.0.0',
+        route_prefix: '/platform-drp/',
+      },
+    }
+
+    expect(resolvePluginBaseUrl(contract)).toBe('/api/platform-drp')
+  })
+
+  it('builds concrete endpoint URLs without making requests', () => {
+    const url = buildPluginEndpointUrl(
+      contract,
+      {
+        method: 'post',
+        path: '/analyze/{experimentId}',
+        pathParams: ['experimentId'],
+        queryParams: [
+          { name: 'dry_run', fieldName: 'dryRun', type: 'boolean', required: false },
+        ],
+        hasBody: true,
+      },
+      { experimentId: 42, dryRun: true, body: { threshold: 0.5 } },
+    )
+
+    expect(url).toBe('/api/drp/analyze/42?dry_run=true')
+    expect(requestConfigs).toHaveLength(0)
+  })
+
+  it('maps plugin contract nav items to AppTopBar page selector metadata', () => {
+    const pageSelectorItems = getPluginPageSelectorItems({
+      ...contract,
+      plugin: {
+        ...contract.plugin,
+        name: 'Dose Designer',
+        description: 'Build dose designs',
+        icon: 'PLUGIN_ICON',
+        navItems: [
+          { path: '/', label: 'Dashboard', icon: 'DASHBOARD_ICON', description: 'Overview' },
+          { id: 'dose-design', path: 'dose-design', label: 'Dose Design' },
+          { path: '/qc/review/', label: 'QC Review', icon: 'QC_ICON' },
+        ],
+      },
+    })
+
+    expect(pageSelectorItems).toEqual([
+      {
+        id: 'dashboard',
+        label: 'Dashboard',
+        to: '/',
+        icon: 'DASHBOARD_ICON',
+        hint: 'Overview',
+      },
+      {
+        id: 'dose-design',
+        label: 'Dose Design',
+        to: '/dose-design',
+        icon: 'PLUGIN_ICON',
+        hint: 'Dose Designer',
+      },
+      {
+        id: 'qc-review',
+        label: 'QC Review',
+        to: '/qc/review',
+        icon: 'QC_ICON',
+        hint: 'Dose Designer',
+      },
+    ])
+    expect(requestConfigs).toHaveLength(0)
+  })
+
+  it('provides a dashboard page selector fallback when contract nav items are absent', () => {
+    expect(getPluginPageSelectorItems({
+      ...contract,
+      plugin: {
+        ...contract.plugin,
+        name: 'Dose Designer',
+        description: 'Build dose designs',
+        icon: 'PLUGIN_ICON',
+        navItems: [],
+      },
+    })).toEqual([
+      {
+        id: 'dashboard',
+        label: 'Dose Designer',
+        to: '/',
+        icon: 'PLUGIN_ICON',
+        hint: 'Build dose designs',
+      },
+    ])
+    expect(requestConfigs).toHaveLength(0)
+  })
+
+  it('can build path-only endpoint URLs with inferred experiment ids', () => {
+    window.history.replaceState({}, '', '/experiments/42/plugins/drp')
+
+    const url = buildPluginEndpointUrl(
+      contract,
+      {
+        method: 'get',
+        path: '/experiments/{experimentId}/summary',
+        pathParams: ['experimentId'],
+        queryParams: [
+          { name: 'include_qc', fieldName: 'includeQc', type: 'boolean', required: false },
+        ],
+      },
+      { includeQc: true },
+      { includeBaseUrl: false },
+    )
+
+    expect(url).toBe('/experiments/42/summary?include_qc=true')
+  })
+
+  it('validates required query params when building endpoint URLs', () => {
+    expect(() => buildPluginEndpointUrl(
+      contract,
+      {
+        method: 'get',
+        path: '/search',
+        queryParams: [
+          { name: 'q', fieldName: 'q', type: 'string', required: true },
+        ],
+      },
+      {},
+    )).toThrow("[MINT SDK] Missing query parameter 'q' for plugin endpoint /search")
+  })
+
+  it('replaces path params and sends request body', async () => {
+    type Client = {
+      analyze(params: { experimentId: number; body: { threshold: number } }): Promise<unknown>
+    }
+    const client = createPluginClient<Client>(contract, {
+      endpoints: {
+        analyze: {
+          method: 'post',
+          path: '/analyze/{experimentId}',
+          pathParams: ['experimentId'],
+          hasBody: true,
+        },
+      },
+    })
+
+    await client.analyze({ experimentId: 42, body: { threshold: 0.5 } })
+
+    expect(requestConfigs[0]!.url).toBe('/analyze/42')
+    expect(requestConfigs[0]!.params).toBeUndefined()
+    expect(requestBodies[0]).toEqual({ threshold: 0.5 })
+  })
+
+  it('infers experimentId path params from the current platform route', async () => {
+    window.history.replaceState({}, '', '/experiments/42/plugins/drp')
+    type Client = {
+      analyze(params: { body: { threshold: number } }): Promise<unknown>
+    }
+    const client = createPluginClient<Client>(contract, {
+      endpoints: {
+        analyze: {
+          method: 'post',
+          path: '/analyze/{experimentId}',
+          pathParams: ['experimentId'],
+          hasBody: true,
+        },
+      },
+    })
+
+    await client.analyze({ body: { threshold: 0.5 } })
+
+    expect(requestConfigs[0]!.url).toBe('/analyze/42')
+    expect(requestConfigs[0]!.params).toBeUndefined()
+    expect(requestBodies[0]).toEqual({ threshold: 0.5 })
+  })
+
+  it('sends query params for non-GET endpoints with request bodies', async () => {
+    type Client = {
+      analyze(params: {
+        experimentId: number
+        dryRun?: boolean
+        body: { threshold: number }
+      }): Promise<unknown>
+    }
+    const client = createPluginClient<Client>(contract, {
+      endpoints: {
+        analyze: {
+          method: 'post',
+          path: '/analyze/{experimentId}',
+          pathParams: ['experimentId'],
+          queryParams: [
+            { name: 'dry_run', fieldName: 'dryRun', type: 'boolean', required: false },
+          ],
+          hasBody: true,
+        },
+      },
+    })
+
+    await client.analyze({
+      experimentId: 42,
+      dryRun: true,
+      body: { threshold: 0.5 },
+    })
+
+    expect(requestConfigs[0]!.url).toBe('/analyze/42')
+    expect(requestConfigs[0]!.params).toEqual({ dry_run: true })
+    expect(requestBodies[0]).toEqual({ threshold: 0.5 })
+  })
+
+  it('throws a clear error before requests with missing request bodies', async () => {
+    type Client = {
+      analyze(params: { experimentId: number; body?: { threshold: number } }): Promise<unknown>
+    }
+    const client = createPluginClient<Client>(contract, {
+      endpoints: {
+        analyze: {
+          method: 'post',
+          path: '/analyze/{experimentId}',
+          pathParams: ['experimentId'],
+          hasBody: true,
+        },
+      },
+    })
+
+    await expect(client.analyze({ experimentId: 42 })).rejects.toThrow(
+      '[MINT SDK] Missing request body for plugin endpoint /analyze/{experimentId}',
+    )
+    expect(requestConfigs).toHaveLength(0)
+  })
+
+  it('sends request bodies and query params for DELETE endpoints', async () => {
+    type Client = {
+      purge(params: { dryRun?: boolean; body: { reason: string } }): Promise<unknown>
+    }
+    const client = createPluginClient<Client>(contract, {
+      endpoints: {
+        purge: {
+          method: 'delete',
+          path: '/purge',
+          queryParams: [
+            { name: 'dry_run', fieldName: 'dryRun', type: 'boolean', required: false },
+          ],
+          hasBody: true,
+        },
+      },
+    })
+
+    await client.purge({ dryRun: true, body: { reason: 'duplicate' } })
+
+    expect(requestConfigs[0]!.url).toBe('/purge')
+    expect(requestConfigs[0]!.params).toEqual({ dry_run: true })
+    expect(requestBodies[0]).toEqual({ reason: 'duplicate' })
+  })
+
+  it('sends non-path GET params as query params', async () => {
+    type Client = {
+      search(params: { experimentId: number; q?: string; limit?: number; includeArchived?: boolean }): Promise<unknown>
+    }
+    const client = createPluginClient<Client>(contract, {
+      endpoints: {
+        search: {
+          method: 'get',
+          path: '/experiments/{experimentId}/search',
+          pathParams: ['experimentId'],
+          queryParams: [
+            { name: 'q', fieldName: 'q', type: 'string', required: false },
+            { name: 'limit', fieldName: 'limit', type: 'number', required: false },
+            { name: 'include_archived', fieldName: 'includeArchived', type: 'boolean', required: false },
+          ],
+        },
+      },
+    })
+
+    await client.search({ experimentId: 42, q: 'glucose', limit: 20, includeArchived: true })
+
+    expect(requestConfigs[0]!.url).toBe('/experiments/42/search')
+    expect(requestConfigs[0]!.params).toEqual({ q: 'glucose', limit: 20, include_archived: true })
+  })
+
+  it('throws a clear error before requests with missing required query params', async () => {
+    type Client = {
+      search(params: { experimentId: number; q?: string }): Promise<unknown>
+    }
+    const client = createPluginClient<Client>(contract, {
+      endpoints: {
+        search: {
+          method: 'get',
+          path: '/experiments/{experimentId}/search',
+          pathParams: ['experimentId'],
+          queryParams: [
+            { name: 'q', fieldName: 'q', type: 'string', required: true },
+          ],
+        },
+      },
+    })
+
+    await expect(client.search({ experimentId: 42 })).rejects.toThrow(
+      "[MINT SDK] Missing query parameter 'q' for plugin endpoint /experiments/{experimentId}/search",
+    )
+    expect(requestConfigs).toHaveLength(0)
+  })
+
+  it('returns the provided client identity from usePluginClient', () => {
+    const client = createPluginClient(contract, { endpoints: {} })
+
+    expect(usePluginClient(client)).toBe(client)
+  })
+
+  it('loads the current experiment from URL conventions', async () => {
+    window.history.replaceState({}, '', '/analysis?experimentId=42')
+    const current = useCurrentExperiment<{ called: string }>({ immediate: false })
+
+    expect(current.experimentId.value).toBe(42)
+    expect(current.hasExperiment.value).toBe(true)
+    expect(current.requireExperimentId()).toBe(42)
+    expect(current.lastLoadedAt.value).toBeNull()
+
+    const pending = current.refresh()
+    expect(current.isLoading.value).toBe(true)
+    await pending
+
+    expect(requestConfigs[0]!.url).toBe('/experiments/42')
+    expect(current.experiment.value).toEqual({ called: '/experiments/42' })
+    expect(current.error.value).toBeNull()
+    expect(current.isLoading.value).toBe(false)
+    expect(current.lastLoadedAt.value).toBeInstanceOf(Date)
+  })
+
+  it('throws a clear error when a current experiment is required but missing', () => {
+    const current = useCurrentExperiment({ immediate: false })
+
+    expect(current.experimentId.value).toBeUndefined()
+    expect(current.hasExperiment.value).toBe(false)
+    expect(() => current.requireExperimentId()).toThrow('[MINT SDK] No current experiment is selected.')
+  })
+
+  it('loads the current experiment from platform route paths', async () => {
+    window.history.replaceState({}, '', '/projects/3/experiments/42/plugins/drp')
+    const current = useCurrentExperiment<{ called: string }>({ immediate: false })
+
+    expect(current.experimentId.value).toBe(42)
+
+    await current.refresh()
+
+    expect(requestConfigs[0]!.url).toBe('/experiments/42')
+  })
+
+  it('loads the current experiment from hash route paths', async () => {
+    window.history.replaceState({}, '', '/plugins/drp#/experiments/43/analysis')
+    const current = useCurrentExperiment<{ called: string }>({ immediate: false })
+
+    expect(current.experimentId.value).toBe(43)
+  })
+
+  it('returns undefined and preserves sync state on current experiment load failure', async () => {
+    window.history.replaceState({}, '', '/analysis?experimentId=42')
+    nextGetError = new Error('network down')
+    const current = useCurrentExperiment<{ called: string }>({ immediate: false })
+
+    const result = await current.refresh()
+
+    expect(result).toBeUndefined()
+    expect(requestConfigs[0]!.url).toBe('/experiments/42')
+    expect(current.experiment.value).toBeUndefined()
+    expect(current.error.value).toBe('network down')
+    expect(current.isLoading.value).toBe(false)
+    expect(current.lastLoadedAt.value).toBeNull()
+  })
+
+  it('prefers platform-injected experiment context and API base', async () => {
+    ;(window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__ = {
+      isIntegrated: true,
+      theme: 'light',
+      platformApiUrl: '/api/platform',
+      currentExperimentId: '7',
+      plugin: {
+        id: 'drp',
+        name: 'DRP',
+        version: '1.0.0',
+        route_prefix: '/drp',
+        api_prefix: '/api/platform-drp',
+      },
+    }
+    const current = useCurrentExperiment<{ called: string }>({ immediate: false })
+
+    expect(current.experimentId.value).toBe(7)
+
+    await current.fetch()
+
+    expect(requestConfigs[0]!.baseURL).toBe('/api/platform')
+    expect(requestConfigs[0]!.url).toBe('/experiments/7')
+  })
+})

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

@@ -9,6 +9,7 @@
  * - 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
  */
 
@@ -96,6 +97,7 @@ describe('usePluginConfig', () => {
     })
     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 () => {
@@ -120,6 +122,7 @@ describe('usePluginConfig', () => {
     expect(patchCall.data).toEqual({ config: { n: 2 } })
     expect(hook.config.value).toEqual({ n: 2 })
     expect(hook.isDirty.value).toBe(false)
+    expect(hook.lastSavedAt.value).toBeInstanceOf(Date)
   })
 
   it('isDirty reflects edits vs last saved snapshot', async () => {
@@ -155,6 +158,7 @@ describe('usePluginConfig', () => {
     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 () => {
@@ -165,6 +169,7 @@ describe('usePluginConfig', () => {
     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 () => {

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

@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'vitest'
+
+import { useRequestSyncState } from '../../composables/useRequestSyncState'
+
+describe('useRequestSyncState', () => {
+  it('starts with idle request state', () => {
+    const state = useRequestSyncState()
+
+    expect(state.loading.value).toBe(false)
+    expect(state.error.value).toBeNull()
+    expect(state.lastLoadedAt.value).toBeNull()
+    expect(state.lastSavedAt.value).toBeNull()
+    expect(state.lastRunAt.value).toBeNull()
+  })
+
+  it('normalizes errors and supports explicit clearing', () => {
+    const state = useRequestSyncState('Default failure')
+
+    expect(state.setError(new Error('Backend rejected request'))).toBe(
+      'Backend rejected request',
+    )
+    expect(state.error.value).toBe('Backend rejected request')
+
+    expect(state.setError('String failure')).toBe('String failure')
+    expect(state.error.value).toBe('String failure')
+
+    expect(state.setError({ message: 'Validation failed' })).toBe('Validation failed')
+    expect(state.error.value).toBe('Validation failed')
+
+    expect(state.setError({ reason: 'unknown' })).toBe('Default failure')
+    state.clearError()
+    expect(state.error.value).toBeNull()
+  })
+
+  it('marks load, save, and run timestamps', () => {
+    const state = useRequestSyncState()
+    const loadedAt = new Date('2026-05-07T09:00:00Z')
+    const savedAt = new Date('2026-05-07T09:01:00Z')
+    const runAt = new Date('2026-05-07T09:02:00Z')
+
+    state.markLoaded(loadedAt)
+    state.markSaved(savedAt)
+    state.markRun(runAt)
+
+    expect(state.lastLoadedAt.value).toBe(loadedAt)
+    expect(state.lastSavedAt.value).toBe(savedAt)
+    expect(state.lastRunAt.value).toBe(runAt)
+  })
+
+  it('wraps successful operations and marks requested sync timestamps', async () => {
+    const state = useRequestSyncState()
+
+    const result = await state.run(async () => {
+      expect(state.loading.value).toBe(true)
+      return { ok: true }
+    }, { success: 'load' })
+
+    expect(result).toEqual({ ok: true })
+    expect(state.loading.value).toBe(false)
+    expect(state.error.value).toBeNull()
+    expect(state.lastLoadedAt.value).toBeInstanceOf(Date)
+    expect(state.lastSavedAt.value).toBeNull()
+    expect(state.lastRunAt.value).toBeNull()
+  })
+
+  it('wraps successful run operations and marks lastRunAt', async () => {
+    const state = useRequestSyncState()
+
+    const result = await state.run(async () => 'done', { success: 'run' })
+
+    expect(result).toBe('done')
+    expect(state.lastLoadedAt.value).toBeNull()
+    expect(state.lastSavedAt.value).toBeNull()
+    expect(state.lastRunAt.value).toBeInstanceOf(Date)
+  })
+
+  it('wraps failed operations, sets error, and rethrows', async () => {
+    const state = useRequestSyncState()
+    const failure = new Error('Network down')
+
+    await expect(state.run(async () => {
+      expect(state.loading.value).toBe(true)
+      throw failure
+    }, { success: 'save' })).rejects.toThrow('Network down')
+
+    expect(state.loading.value).toBe(false)
+    expect(state.error.value).toBe('Network down')
+    expect(state.lastLoadedAt.value).toBeNull()
+    expect(state.lastSavedAt.value).toBeNull()
+    expect(state.lastRunAt.value).toBeNull()
+  })
+})