@morscherlab/mint-sdk 1.0.51 → 1.0.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morscherlab/mint-sdk",
-  "version": "1.0.51",
+  "version": "1.0.53",
   "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__/components/JobsStatusTray.test.ts

@@ -0,0 +1,141 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it, vi } from 'vitest'
+
+import JobsStatusTray from '../../components/JobsStatusTray.vue'
+import type { JobStateInput, JobStatus } from '../../types/jobs'
+
+function job(status: JobStatus, id: string = status): JobStateInput {
+  return {
+    id,
+    job_id: id,
+    kind: 'analysis',
+    name: `Job ${id}`,
+    status,
+    progress: {
+      current_file: 0,
+      total_files: 0,
+      current_filename: null,
+      percent: 0,
+      message: '',
+      stage: status,
+    },
+    queue_position: 0,
+    warnings: [],
+    error: null,
+    output_path: null,
+    save_path: null,
+    session_id: null,
+    folders: [],
+    folder_path: null,
+    user_id: '1',
+    owner_user_id: '1',
+    experiment_id: null,
+    extraction_result_id: null,
+    metadata: {},
+    created_at: '2026-07-14T10:00:00+00:00',
+    started_at: null,
+    completed_at: null,
+  }
+}
+
+async function openTray(options: {
+  jobs: JobStateInput[]
+  adapter?: Record<string, unknown>
+}) {
+  const wrapper = mount(JobsStatusTray, {
+    attachTo: document.body,
+    props: {
+      ...options,
+      loadOnMount: false,
+      teleportTo: false,
+    },
+  })
+  await wrapper.get('.mint-jobs-tray__trigger').trigger('click')
+  return wrapper
+}
+
+describe('JobsStatusTray', () => {
+  it('shows awaiting input as active without default actions', async () => {
+    const wrapper = await openTray({ jobs: [job('awaiting_input')] })
+
+    expect([
+      wrapper.text().includes('Waiting for input'),
+      wrapper.find('[aria-label="Cancel job"]').exists(),
+      wrapper.find('[aria-label="Delete job"]').exists(),
+    ]).toEqual([true, false, false])
+  })
+
+  it('shows only actions supported by both capability and adapter', async () => {
+    const wrapper = await openTray({
+      jobs: [
+        { ...job('awaiting_input', 'input'), can_cancel: true },
+        { ...job('completed', 'done'), can_delete: true },
+      ],
+      adapter: {
+        cancelJob: vi.fn(),
+        deleteJob: vi.fn(),
+      },
+    })
+
+    expect([
+      wrapper.find('[aria-label="Cancel job"]').exists(),
+      wrapper.find('[aria-label="Delete job"]').exists(),
+    ]).toEqual([true, false])
+
+    await wrapper.get('[role="tab"][data-tab="history"]').trigger('click')
+    expect(wrapper.find('[aria-label="Delete job"]').exists()).toBe(true)
+  })
+
+  it('exposes dialog state and closes on Escape', async () => {
+    const wrapper = await openTray({ jobs: [job('running')] })
+    const trigger = wrapper.get('.mint-jobs-tray__trigger')
+
+    await wrapper.get('[role="dialog"]').trigger('keydown', { key: 'Escape' })
+
+    expect([trigger.attributes('aria-expanded'), wrapper.find('[role="dialog"]').exists()]).toEqual([
+      'false',
+      false,
+    ])
+  })
+
+  it('renders an individual delete action for an active capable job', async () => {
+    const wrapper = await openTray({
+      jobs: [{ ...job('awaiting_input'), can_delete: true }],
+      adapter: { deleteJob: vi.fn() },
+    })
+
+    expect(wrapper.find('[aria-label="Delete job"]').exists()).toBe(true)
+  })
+
+  it('traps forward Tab navigation inside the modal dialog', async () => {
+    const wrapper = await openTray({ jobs: [job('running')] })
+    const focusable = wrapper.findAll('button')
+    const firstInsidePanel = wrapper.get('[aria-label="Close jobs"]')
+    const lastInsidePanel = focusable[focusable.length - 1]!
+    lastInsidePanel.element.focus()
+
+    await wrapper.get('[role="dialog"]').trigger('keydown', { key: 'Tab' })
+
+    expect(document.activeElement).toBe(firstInsidePanel.element)
+  })
+
+  it('traps reverse Tab navigation from the dialog container', async () => {
+    const wrapper = await openTray({ jobs: [job('running')] })
+    const panel = wrapper.get('[role="dialog"]')
+    const focusable = panel.findAll('button')
+    const panelElement = panel.element as HTMLElement
+    panelElement.focus()
+
+    await panel.trigger('keydown', { key: 'Tab', shiftKey: true })
+
+    expect(document.activeElement).toBe(focusable[focusable.length - 1]!.element)
+  })
+
+  it('exposes job selection through a keyboard-accessible button', async () => {
+    const wrapper = await openTray({ jobs: [job('running')] })
+
+    await wrapper.get('.mint-jobs-tray__job-select').trigger('click')
+
+    expect(wrapper.emitted('select')?.[0]?.[0]).toMatchObject({ job_id: 'running' })
+  })
+})

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

@@ -0,0 +1,241 @@
+import { mount } from '@vue/test-utils'
+import { defineComponent, nextTick, ref, shallowRef } from 'vue'
+import { describe, expect, it, vi } from 'vitest'
+
+import { useJobsStatusTray, type UseJobsStatusTrayOptions } from '../../composables/useJobsStatusTray'
+import type { JobState, JobStateInput, JobStatus } from '../../types/jobs'
+
+function job(status: JobStatus, id: string = status): JobStateInput {
+  return {
+    id,
+    job_id: id,
+    kind: 'analysis',
+    name: id,
+    status,
+    progress: {
+      current_file: 0,
+      total_files: 0,
+      current_filename: null,
+      percent: status === 'running' ? 42 : 0,
+      message: '',
+      stage: status,
+    },
+    queue_position: 0,
+    warnings: [],
+    error: null,
+    output_path: null,
+    save_path: null,
+    session_id: null,
+    folders: [],
+    folder_path: null,
+    user_id: '1',
+    owner_user_id: '1',
+    experiment_id: null,
+    extraction_result_id: null,
+    metadata: {},
+    created_at: '2026-07-14T10:00:00+00:00',
+    started_at: null,
+    completed_at: null,
+  }
+}
+
+function mountComposable(options: UseJobsStatusTrayOptions) {
+  let tray!: ReturnType<typeof useJobsStatusTray>
+  const wrapper = mount(defineComponent({
+    setup() {
+      tray = useJobsStatusTray(options)
+      return () => null
+    },
+  }))
+  return { tray, wrapper }
+}
+
+function deferred<T>(): {
+  promise: Promise<T>
+  resolve: (value: T) => void
+} {
+  let resolve!: (value: T) => void
+  const promise = new Promise<T>((done) => {
+    resolve = done
+  })
+  return { promise, resolve }
+}
+
+describe('useJobsStatusTray', () => {
+  it('keeps awaiting input jobs in the active group', () => {
+    const { tray } = mountComposable({
+      jobs: [job('awaiting_input')],
+      loadOnMount: false,
+    })
+
+    expect(tray.activeJobs.value.map(item => item.job_id)).toEqual(['awaiting_input'])
+  })
+
+  it('replaces stale jobs when an SSE snapshot arrives', () => {
+    const { tray } = mountComposable({ jobs: [job('running', 'old')], loadOnMount: false })
+
+    tray.applyStreamMessage({
+      event: 'snapshot',
+      data: { jobs: [job('queued', 'new')] },
+    })
+
+    expect(tray.jobs.value.map(item => item.job_id)).toEqual(['new'])
+  })
+
+  it('moves an SSE terminal update into history', () => {
+    const { tray } = mountComposable({ jobs: [job('running', 'fit')], loadOnMount: false })
+
+    tray.applyStreamMessage({ event: 'terminal', data: job('completed', 'fit') })
+
+    expect(tray.historyJobs.value.map(item => item.job_id)).toEqual(['fit'])
+  })
+
+  it('does not call a cancel adapter when the capability is disabled', async () => {
+    const cancelJob = vi.fn()
+    const { tray } = mountComposable({
+      jobs: [{ ...job('running'), can_cancel: false }],
+      adapter: { cancelJob },
+      loadOnMount: false,
+    })
+
+    await tray.cancelJob(tray.jobs.value[0]!)
+
+    expect(cancelJob).not.toHaveBeenCalled()
+  })
+
+  it('does not let a stale list response overwrite an SSE update', async () => {
+    let resolveList!: (jobs: JobStateInput[]) => void
+    const listJobs = vi.fn(() => new Promise<JobStateInput[]>((resolve) => {
+      resolveList = resolve
+    }))
+    const { tray } = mountComposable({
+      adapter: { listJobs },
+      loadOnMount: false,
+    })
+
+    const refresh = tray.refresh()
+    tray.applyStreamMessage({ event: 'job', data: job('running', 'live') })
+    resolveList([job('queued', 'stale')])
+    await refresh
+    await nextTick()
+
+    expect(tray.jobs.value.map(item => item.job_id)).toEqual(['live'])
+  })
+
+  it('passes only explicitly deletable jobs to the bulk clear adapter', async () => {
+    const clearFinishedJobs = vi.fn(async (_jobs: readonly JobState[]) => undefined)
+    const { tray } = mountComposable({
+      jobs: [
+        job('completed', 'legacy-deletable'),
+        { ...job('failed', 'retained'), can_delete: false },
+      ],
+      adapter: { clearFinishedJobs },
+      loadOnMount: false,
+    })
+
+    await tray.clearFinished()
+
+    expect(clearFinishedJobs.mock.calls[0]![0].map(item => item.job_id)).toEqual([
+      'legacy-deletable',
+    ])
+  })
+
+  it('does not include active deletable jobs in bulk clear targets', () => {
+    const { tray } = mountComposable({
+      jobs: [{ ...job('awaiting_input'), can_delete: true }],
+      loadOnMount: false,
+    })
+
+    expect(tray.deletableJobs.value).toEqual([])
+  })
+
+  it('does not let a late cancel response overwrite a newer SSE state', async () => {
+    const pending = deferred<JobStateInput>()
+    const { tray } = mountComposable({
+      jobs: [job('running', 'fit')],
+      adapter: { cancelJob: async () => pending.promise },
+      loadOnMount: false,
+    })
+
+    const cancellation = tray.cancelJob(tray.jobs.value[0]!)
+    tray.applyStreamMessage({ event: 'terminal', data: job('completed', 'fit') })
+    pending.resolve(job('cancelled', 'fit'))
+    await cancellation
+
+    expect(tray.jobs.value[0]!.status).toBe('completed')
+  })
+
+  it('applies a cancel response after an unrelated job update', async () => {
+    const pending = deferred<JobStateInput>()
+    const { tray } = mountComposable({
+      jobs: [job('running', 'fit'), job('running', 'export')],
+      adapter: { cancelJob: async () => pending.promise },
+      loadOnMount: false,
+    })
+
+    const cancellation = tray.cancelJob(tray.jobs.value[0]!)
+    tray.applyStreamMessage({ event: 'job', data: job('running', 'export') })
+    pending.resolve(job('cancelled', 'fit'))
+    await cancellation
+
+    expect(tray.jobs.value.find(item => item.job_id === 'fit')?.status).toBe('cancelled')
+  })
+
+  it('refreshes instead of removing every target after a partial bulk clear', async () => {
+    const listJobs = vi.fn(async () => [job('completed', 'retained')])
+    const clearFinishedJobs = vi.fn(async () => 1)
+    const { tray } = mountComposable({
+      jobs: [job('completed', 'deleted'), job('completed', 'retained')],
+      adapter: { listJobs, clearFinishedJobs },
+      loadOnMount: false,
+    })
+
+    const cleared = await tray.clearFinished()
+
+    expect([
+      cleared,
+      listJobs.mock.calls.length,
+      tray.jobs.value.map(item => item.job_id),
+    ]).toEqual([false, 1, ['retained']])
+  })
+
+  it('uses a replacement reactive adapter for later actions', async () => {
+    const first = vi.fn(async () => undefined)
+    const second = vi.fn(async () => undefined)
+    const adapter = shallowRef({ cancelJob: first })
+    const { tray } = mountComposable({
+      jobs: [job('running')],
+      adapter,
+      loadOnMount: false,
+    })
+    adapter.value = { cancelJob: second }
+
+    await tray.cancelJob(tray.jobs.value[0]!)
+
+    expect([first.mock.calls.length, second.mock.calls.length]).toEqual([0, 1])
+  })
+
+  it('applies the latest message from a replacement stream immediately', async () => {
+    const eventStream = shallowRef({
+      isConnected: ref(true),
+      isConnecting: ref(false),
+      error: ref<string | null>(null),
+      lastMessage: shallowRef({
+        event: 'snapshot',
+        data: { jobs: [job('queued', 'replacement')] },
+        raw: '',
+      }),
+      lastEventId: ref<string | null>(null),
+      start: vi.fn(),
+      stop: vi.fn(),
+    })
+
+    const { tray } = mountComposable({
+      eventStream,
+      loadOnMount: false,
+    })
+    await nextTick()
+
+    expect(tray.jobs.value.map(item => item.job_id)).toEqual(['replacement'])
+  })
+})

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

@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { createPinia, setActivePinia } from 'pinia'
 import axios, { type AxiosRequestConfig } from 'axios'
+import { watch } from 'vue'
 
 import {
   buildPluginEndpointUrl,
@@ -30,6 +31,33 @@ const contract: PluginContract = {
   hash: 'sha256:test',
 }
 
+function deferred<T>(): {
+  promise: Promise<T>
+  resolve: (value: T) => void
+} {
+  let resolve!: (value: T) => void
+  const promise = new Promise<T>((done) => {
+    resolve = done
+  })
+  return { promise, resolve }
+}
+
+function pendingEventStreamResponse(): {
+  response: Response
+  close: () => void
+} {
+  let streamController!: ReadableStreamDefaultController<Uint8Array>
+  const body = new ReadableStream<Uint8Array>({
+    start(controller) {
+      streamController = controller
+    },
+  })
+  return {
+    response: new Response(body, { status: 200 }),
+    close: () => streamController.close(),
+  }
+}
+
 describe('usePluginClient', () => {
   let requestConfigs: AxiosRequestConfig[] = []
   let requestBodies: unknown[] = []
@@ -99,6 +127,7 @@ describe('usePluginClient', () => {
   afterEach(() => {
     vi.useRealTimers()
     vi.restoreAllMocks()
+    vi.unstubAllGlobals()
     vi.unstubAllEnvs()
     window.history.replaceState({}, '', '/')
     delete (window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__
@@ -522,6 +551,268 @@ describe('usePluginClient', () => {
     expect(stream.lastEventId.value).toBe('7')
   })
 
+  it('parses generated typed event streams as JSON by default', async () => {
+    const onMessage = vi.fn()
+    const streamBody = new ReadableStream({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode('event: job\ndata: {"job_id":"fit"}\n\n'))
+        controller.close()
+      },
+    })
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(streamBody, { status: 200 })))
+
+    usePluginEventStream<{ job_id: string }>(
+      contract,
+      {
+        method: 'get',
+        path: '/jobs/events',
+        eventStream: true,
+        responseType: 'JobStatePayload | JobSnapshotPayload',
+      },
+      { reconnect: false, onMessage },
+    )
+
+    await vi.waitFor(() => {
+      expect(onMessage).toHaveBeenCalledOnce()
+    })
+    expect(onMessage.mock.calls[0]![0].data).toEqual({ job_id: 'fit' })
+  })
+
+  it('should deliver terminal enrichment on the original generated stream', async () => {
+    type JobStreamData = {
+      jobs?: Array<Record<string, unknown>>
+      job_id?: string
+      can_delete?: boolean
+      output_path?: string | null
+    }
+    const onMessage = vi.fn()
+    const streamBody = new ReadableStream({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode(
+          'event: snapshot\ndata: {"jobs":[{"job_id":"fit","can_delete":false,"output_path":null}]}\n\n'
+          + 'event: terminal\ndata: {"job_id":"fit","can_delete":true,"output_path":"/results/final.csv"}\n\n',
+        ))
+        controller.close()
+      },
+    })
+    const fetchMock = vi.fn(async () => new Response(streamBody, { status: 200 }))
+    vi.stubGlobal('fetch', fetchMock)
+
+    const stream = usePluginEventStream<JobStreamData>(
+      contract,
+      {
+        method: 'get',
+        path: '/jobs/events',
+        eventStream: true,
+        responseType: 'JobStatePayload | JobSnapshotPayload',
+      },
+      { reconnect: false, onMessage },
+    )
+
+    await vi.waitFor(() => {
+      expect({
+        fetches: fetchMock.mock.calls.length,
+        events: onMessage.mock.calls.map(([message]) => message.event),
+        last: stream.lastMessage.value?.data,
+      }).toEqual({
+        fetches: 1,
+        events: ['snapshot', 'terminal'],
+        last: {
+          job_id: 'fit',
+          can_delete: true,
+          output_path: '/results/final.csv',
+        },
+      })
+    })
+  })
+
+  it('keeps generated string event streams as text by default', async () => {
+    const onMessage = vi.fn()
+    const streamBody = new ReadableStream({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode('event: ready\ndata: ready\n\n'))
+        controller.close()
+      },
+    })
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(streamBody, { status: 200 })))
+
+    usePluginEventStream(
+      contract,
+      {
+        method: 'get',
+        path: '/jobs/events',
+        eventStream: true,
+        responseType: 'string',
+      },
+      { reconnect: false, onMessage },
+    )
+
+    await vi.waitFor(() => {
+      expect(onMessage).toHaveBeenCalledOnce()
+    })
+    expect(onMessage.mock.calls[0]![0].data).toBe('ready')
+  })
+
+  it('should keep start idempotent when an event stream is active', async () => {
+    const active = pendingEventStreamResponse()
+    const fetchMock = vi.fn(async () => active.response)
+    vi.stubGlobal('fetch', fetchMock)
+    const stream = usePluginEventStream(
+      contract,
+      { method: 'get', path: '/downloads/events' },
+      { immediate: false },
+    )
+
+    try {
+      stream.start()
+      stream.start()
+      await Promise.resolve()
+
+      expect(fetchMock).toHaveBeenCalledOnce()
+    } finally {
+      stream.stop()
+      active.close()
+    }
+  })
+
+  it('should keep replacement stream connected when an old connection finishes', async () => {
+    const oldFetch = deferred<Response>()
+    const replacement = pendingEventStreamResponse()
+    const fetchMock = vi.fn()
+      .mockReturnValueOnce(oldFetch.promise)
+      .mockResolvedValueOnce(replacement.response)
+    vi.stubGlobal('fetch', fetchMock)
+    const stream = usePluginEventStream(
+      contract,
+      { method: 'get', path: '/downloads/events' },
+      { immediate: false },
+    )
+
+    try {
+      stream.start()
+      stream.stop()
+      stream.start()
+      await Promise.resolve()
+      await Promise.resolve()
+      oldFetch.resolve(new Response('', { status: 200 }))
+      await Promise.resolve()
+      await Promise.resolve()
+
+      expect(stream.isConnected.value).toBe(true)
+    } finally {
+      stream.stop()
+      replacement.close()
+    }
+  })
+
+  it('should not reconnect after a stale event stream finishes', async () => {
+    vi.useFakeTimers()
+    const oldFetch = deferred<Response>()
+    const replacement = pendingEventStreamResponse()
+    const fetchMock = vi.fn()
+      .mockReturnValueOnce(oldFetch.promise)
+      .mockResolvedValueOnce(replacement.response)
+      .mockResolvedValue(new Response('', { status: 200 }))
+    vi.stubGlobal('fetch', fetchMock)
+    const stream = usePluginEventStream(
+      contract,
+      { method: 'get', path: '/downloads/events' },
+      { immediate: false, reconnectDelayMs: 10 },
+    )
+
+    try {
+      stream.start()
+      stream.stop()
+      stream.start()
+      await Promise.resolve()
+      oldFetch.resolve(new Response('', { status: 200 }))
+      await Promise.resolve()
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(fetchMock).toHaveBeenCalledTimes(2)
+    } finally {
+      stream.stop()
+      replacement.close()
+    }
+  })
+
+  it('should not call onOpen after a synchronous restart invalidates the stream', async () => {
+    const oldConnection = pendingEventStreamResponse()
+    const replacement = pendingEventStreamResponse()
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce(oldConnection.response)
+      .mockResolvedValueOnce(replacement.response)
+    vi.stubGlobal('fetch', fetchMock)
+    const onOpen = vi.fn()
+    const stream = usePluginEventStream(
+      contract,
+      { method: 'get', path: '/downloads/events' },
+      { immediate: false, onOpen },
+    )
+    let restarted = false
+    const stopWatching = watch(
+      stream.isConnected,
+      (connected) => {
+        if (!connected || restarted) return
+        restarted = true
+        stream.stop()
+        stream.start()
+      },
+      { flush: 'sync' },
+    )
+
+    try {
+      stream.start()
+      await Promise.resolve()
+      await Promise.resolve()
+      await Promise.resolve()
+
+      expect(onOpen).toHaveBeenCalledOnce()
+    } finally {
+      stopWatching()
+      stream.stop()
+      oldConnection.close()
+      replacement.close()
+    }
+  })
+
+  it('should not fetch after a synchronous setup restart invalidates the stream', async () => {
+    const replacement = pendingEventStreamResponse()
+    const stale = pendingEventStreamResponse()
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce(replacement.response)
+      .mockResolvedValueOnce(stale.response)
+    vi.stubGlobal('fetch', fetchMock)
+    const stream = usePluginEventStream(
+      contract,
+      { method: 'get', path: '/downloads/events' },
+      { immediate: false },
+    )
+    let restarted = false
+    const stopWatching = watch(
+      stream.isConnecting,
+      (connecting) => {
+        if (!connecting || restarted) return
+        restarted = true
+        stream.stop()
+        stream.start()
+      },
+      { flush: 'sync' },
+    )
+
+    try {
+      stream.start()
+      await Promise.resolve()
+
+      expect(fetchMock).toHaveBeenCalledOnce()
+    } finally {
+      stopWatching()
+      stream.stop()
+      replacement.close()
+      stale.close()
+    }
+  })
+
   it('can build path-only endpoint URLs with inferred experiment ids', () => {
     window.history.replaceState({}, '', '/experiments/42/plugins/drp')