@morscherlab/mint-sdk 1.0.51 → 1.0.52

package/src/composables/useJobsStatusTray.ts

@@ -0,0 +1,304 @@
+import {
+  computed,
+  onMounted,
+  onUnmounted,
+  ref,
+  shallowRef,
+  toValue,
+  watch,
+  type ComputedRef,
+  type MaybeRefOrGetter,
+  type Ref,
+  type ShallowRef,
+} from 'vue'
+
+import { isActiveJobStatus, normalizeJobState } from '../jobs'
+import type {
+  JobListPayload,
+  JobState,
+  JobStateInput,
+  JobStreamData,
+} from '../types/jobs'
+import type {
+  PluginEventStreamMessage,
+  UsePluginEventStreamReturn,
+} from './usePluginClient'
+
+export type JobsStatusTrayTab = 'active' | 'history'
+
+export interface JobsStatusTrayAdapter {
+  listJobs?: () => Promise<JobListPayload | readonly JobStateInput[]>
+  cancelJob?: (job: JobState) => Promise<JobStateInput | void>
+  deleteJob?: (job: JobState) => Promise<boolean | void>
+  clearFinishedJobs?: (jobs: readonly JobState[]) => Promise<number | void>
+}
+
+export interface UseJobsStatusTrayOptions {
+  jobs?: MaybeRefOrGetter<readonly JobStateInput[] | undefined>
+  adapter?: MaybeRefOrGetter<JobsStatusTrayAdapter | undefined>
+  eventStream?: MaybeRefOrGetter<UsePluginEventStreamReturn<JobStreamData> | undefined>
+  loadOnMount?: boolean
+}
+
+export interface JobStreamMessage {
+  event: string
+  data: JobStreamData
+}
+
+export interface UseJobsStatusTrayReturn {
+  jobs: ShallowRef<JobState[]>
+  activeJobs: ComputedRef<JobState[]>
+  historyJobs: ComputedRef<JobState[]>
+  deletableJobs: ComputedRef<JobState[]>
+  featuredJob: ComputedRef<JobState | null>
+  isOpen: Ref<boolean>
+  activeTab: Ref<JobsStatusTrayTab>
+  isLoading: Ref<boolean>
+  error: ShallowRef<string | null>
+  pendingJobIds: Ref<Set<string>>
+  open: () => void
+  close: () => void
+  toggle: () => void
+  refresh: () => Promise<boolean>
+  applyStreamMessage: (message: JobStreamMessage) => void
+  cancelJob: (job: JobState) => Promise<boolean>
+  deleteJob: (job: JobState) => Promise<boolean>
+  clearFinished: () => Promise<boolean>
+  isPending: (job: JobState) => boolean
+}
+
+function responseJobs(
+  response: JobListPayload | readonly JobStateInput[],
+): readonly JobStateInput[] {
+  return 'jobs' in response ? response.jobs : response
+}
+
+function isSnapshotPayload(data: JobStreamData): data is { jobs: JobStateInput[] } {
+  return 'jobs' in data && Array.isArray(data.jobs)
+}
+
+function errorMessage(error: unknown, fallback: string): string {
+  return error instanceof Error ? error.message : fallback
+}
+
+/** Headless state and action controller for the standard SDK jobs tray. */
+export function useJobsStatusTray(
+  options: UseJobsStatusTrayOptions = {},
+): UseJobsStatusTrayReturn {
+  const jobs = shallowRef<JobState[]>([])
+  const isOpen = ref(false)
+  const activeTab = ref<JobsStatusTrayTab>('active')
+  const isLoading = ref(false)
+  const error = shallowRef<string | null>(null)
+  const pendingJobIds = ref(new Set<string>())
+  const jobRevisions = new Map<string, number>()
+  let stateRevision = 0
+  let requestGeneration = 0
+  let active = true
+  const adapter = computed(() => toValue(options.adapter))
+
+  const activeJobs = computed(() => jobs.value.filter(job => isActiveJobStatus(job.status)))
+  const historyJobs = computed(() => jobs.value.filter(job => !isActiveJobStatus(job.status)))
+  const deletableJobs = computed(() => historyJobs.value.filter(job => job.can_delete))
+  const featuredJob = computed(() => activeJobs.value[0] ?? historyJobs.value[0] ?? null)
+
+  function bumpJobRevision(jobId: string): void {
+    jobRevisions.set(jobId, (jobRevisions.get(jobId) ?? 0) + 1)
+  }
+
+  function replaceJobs(nextJobs: readonly JobStateInput[]): void {
+    const normalized = nextJobs.map(normalizeJobState)
+    const touchedJobIds = new Set([
+      ...jobs.value.map(job => job.job_id),
+      ...normalized.map(job => job.job_id),
+    ])
+    touchedJobIds.forEach(bumpJobRevision)
+    jobs.value = normalized
+    stateRevision += 1
+  }
+
+  function upsertJob(nextJob: JobStateInput): void {
+    const normalized = normalizeJobState(nextJob)
+    const existingIndex = jobs.value.findIndex(job => job.job_id === normalized.job_id)
+    if (existingIndex === -1) {
+      jobs.value = [normalized, ...jobs.value]
+    } else {
+      const nextJobs = [...jobs.value]
+      nextJobs[existingIndex] = normalized
+      jobs.value = nextJobs
+    }
+    bumpJobRevision(normalized.job_id)
+    stateRevision += 1
+  }
+
+  function removeJobs(jobIds: Set<string>): void {
+    jobs.value = jobs.value.filter(job => !jobIds.has(job.job_id))
+    jobIds.forEach(bumpJobRevision)
+    stateRevision += 1
+  }
+
+  function setPending(jobId: string, pending: boolean): void {
+    const next = new Set(pendingJobIds.value)
+    if (pending) next.add(jobId)
+    else next.delete(jobId)
+    pendingJobIds.value = next
+  }
+
+  function applyStreamMessage(message: JobStreamMessage): void {
+    if (!active) return
+    if (message.event === 'snapshot' && isSnapshotPayload(message.data)) {
+      replaceJobs(message.data.jobs)
+      return
+    }
+    if (
+      (message.event === 'job' || message.event === 'terminal')
+      && !isSnapshotPayload(message.data)
+    ) {
+      upsertJob(message.data)
+    }
+  }
+
+  async function refresh(): Promise<boolean> {
+    const listJobs = adapter.value?.listJobs
+    if (!listJobs) return false
+    const generation = ++requestGeneration
+    const revision = stateRevision
+    isLoading.value = true
+    error.value = null
+    try {
+      const response = await listJobs()
+      if (!active || generation !== requestGeneration || revision !== stateRevision) {
+        return false
+      }
+      replaceJobs(responseJobs(response))
+      return true
+    } catch (cause) {
+      if (active && generation === requestGeneration) {
+        error.value = errorMessage(cause, 'Failed to load jobs')
+      }
+      return false
+    } finally {
+      if (active && generation === requestGeneration) isLoading.value = false
+    }
+  }
+
+  async function cancelJob(job: JobState): Promise<boolean> {
+    const cancel = adapter.value?.cancelJob
+    if (!job.can_cancel || !cancel || pendingJobIds.value.has(job.job_id)) {
+      return false
+    }
+    const revision = jobRevisions.get(job.job_id) ?? 0
+    setPending(job.job_id, true)
+    error.value = null
+    try {
+      const updated = await cancel(job)
+      if (!active) return false
+      if (revision === (jobRevisions.get(job.job_id) ?? 0)) {
+        if (updated) upsertJob(updated)
+        else await refresh()
+      }
+      return true
+    } catch (cause) {
+      if (active) error.value = errorMessage(cause, 'Failed to cancel job')
+      return false
+    } finally {
+      if (active) setPending(job.job_id, false)
+    }
+  }
+
+  async function deleteJob(job: JobState): Promise<boolean> {
+    const deleteJobWithAdapter = adapter.value?.deleteJob
+    if (!job.can_delete || !deleteJobWithAdapter || pendingJobIds.value.has(job.job_id)) {
+      return false
+    }
+    setPending(job.job_id, true)
+    error.value = null
+    try {
+      const deleted = await deleteJobWithAdapter(job)
+      if (!active) return false
+      if (deleted === false) await refresh()
+      else removeJobs(new Set([job.job_id]))
+      return deleted !== false
+    } catch (cause) {
+      if (active) error.value = errorMessage(cause, 'Failed to delete job')
+      return false
+    } finally {
+      if (active) setPending(job.job_id, false)
+    }
+  }
+
+  async function clearFinished(): Promise<boolean> {
+    const targets = deletableJobs.value
+    if (targets.length === 0) return false
+    error.value = null
+    try {
+      const currentAdapter = adapter.value
+      if (currentAdapter?.clearFinishedJobs) {
+        const deleted = await currentAdapter.clearFinishedJobs(targets)
+        if (!active) return false
+        if (typeof deleted === 'number' && deleted !== targets.length) {
+          await refresh()
+          return false
+        }
+        removeJobs(new Set(targets.map(job => job.job_id)))
+        return true
+      }
+      if (!currentAdapter?.deleteJob) return false
+      const results = await Promise.all(targets.map(job => deleteJob(job)))
+      return results.every(Boolean)
+    } catch (cause) {
+      if (active) error.value = errorMessage(cause, 'Failed to clear jobs')
+      return false
+    }
+  }
+
+  if (options.jobs !== undefined) {
+    watch(
+      () => toValue(options.jobs),
+      value => {
+        if (value) replaceJobs(value)
+      },
+      { immediate: true, deep: true },
+    )
+  }
+
+  if (options.eventStream !== undefined) {
+    watch(
+      () => toValue(options.eventStream)?.lastMessage.value ?? null,
+      (message: PluginEventStreamMessage<JobStreamData> | null) => {
+        if (message) applyStreamMessage(message)
+      },
+      { immediate: true },
+    )
+  }
+
+  onMounted(() => {
+    if (options.loadOnMount !== false) void refresh()
+  })
+  onUnmounted(() => {
+    active = false
+    requestGeneration += 1
+  })
+
+  return {
+    jobs,
+    activeJobs,
+    historyJobs,
+    deletableJobs,
+    featuredJob,
+    isOpen,
+    activeTab,
+    isLoading,
+    error,
+    pendingJobIds,
+    open: () => { isOpen.value = true },
+    close: () => { isOpen.value = false },
+    toggle: () => { isOpen.value = !isOpen.value },
+    refresh,
+    applyStreamMessage,
+    cancelJob,
+    deleteJob,
+    clearFinished,
+    isPending: job => pendingJobIds.value.has(job.job_id),
+  }
+}

package/src/composables/usePluginClient.ts

@@ -31,6 +31,7 @@ export interface PluginEndpointContract {
   queryParams?: PluginEndpointParamContract[]
   requestType?: string | null
   responseType?: string | null
+  eventStream?: boolean
 }
 
 export interface PluginEndpointParamContract {
@@ -82,6 +83,8 @@ export interface PluginEndpointDefinition {
   pathParams?: PluginEndpointParamDefinition[]
   queryParams?: PluginEndpointParamDefinition[]
   hasBody?: boolean
+  eventStream?: boolean
+  responseType?: string | null
 }
 
 export type PluginEndpointParamDefinition = string | {
@@ -177,7 +180,7 @@ export interface PluginEventStreamOptions<TData = string> {
   reconnect?: boolean
   /** Delay before reconnecting after a stream failure or close. Defaults to 2000ms. */
   reconnectDelayMs?: number
-  /** Parse `data:` as JSON before calling onMessage. */
+  /** Parse `data:` as JSON. Defaults to true for typed endpoints and false otherwise. */
   parseJson?: boolean
   /** Fetch credentials mode. Defaults to same-origin. */
   credentials?: RequestCredentials
@@ -662,9 +665,12 @@ export function usePluginEventStream<TData = string>(
   const error = ref<string | null>(null)
   const lastMessage = shallowRef<PluginEventStreamMessage<TData> | null>(null)
   const lastEventId = ref<string | null>(null)
+  const responseType = endpoint.responseType?.trim()
+  const parseJson = options.parseJson ?? Boolean(responseType && responseType !== 'string')
   let controller: AbortController | null = null
   let reconnectTimer: ReturnType<typeof setTimeout> | null = null
   let stopped = true
+  let generation = 0
 
   function clearReconnectTimer(): void {
     if (reconnectTimer !== null) {
@@ -673,15 +679,31 @@ export function usePluginEventStream<TData = string>(
     }
   }
 
-  function scheduleReconnect(): void {
-    if (stopped || options.reconnect === false) return
+  function ownsConnection(
+    connectionGeneration: number,
+    connectionController: AbortController,
+  ): boolean {
+    return !stopped
+      && generation === connectionGeneration
+      && controller === connectionController
+  }
+
+  function scheduleReconnect(connectionGeneration: number): void {
+    if (
+      stopped
+      || generation !== connectionGeneration
+      || options.reconnect === false
+    ) return
     clearReconnectTimer()
     reconnectTimer = setTimeout(() => {
-      void connect()
+      reconnectTimer = null
+      if (stopped || generation !== connectionGeneration) return
+      void connect(connectionGeneration)
     }, options.reconnectDelayMs ?? 2000)
   }
 
-  async function connect(): Promise<void> {
+  async function connect(connectionGeneration: number): Promise<void> {
+    if (stopped || generation !== connectionGeneration) return
     if (endpoint.method !== 'get') {
       throw new Error(`[MINT SDK] Plugin event streams must use GET; got ${endpoint.method}`)
     }
@@ -690,9 +712,12 @@ export function usePluginEventStream<TData = string>(
     }
 
     controller?.abort()
-    controller = new AbortController()
+    const connectionController = new AbortController()
+    controller = connectionController
     isConnecting.value = true
+    if (!ownsConnection(connectionGeneration, connectionController)) return
     error.value = null
+    if (!ownsConnection(connectionGeneration, connectionController)) return
 
     try {
       const url = buildPluginEndpointUrl(contract, endpoint, payload, {
@@ -702,9 +727,11 @@ export function usePluginEventStream<TData = string>(
         method: 'GET',
         headers: streamHeaders(options as PluginEventStreamOptions<unknown>),
         credentials: options.credentials ?? 'same-origin',
-        signal: controller.signal,
+        signal: connectionController.signal,
       })
 
+      if (!ownsConnection(connectionGeneration, connectionController)) return
+
       if (!response.ok) {
         throw new Error(`Plugin event stream failed with HTTP ${response.status}`)
       }
@@ -712,14 +739,17 @@ export function usePluginEventStream<TData = string>(
         throw new Error('Plugin event stream response did not include a readable body.')
       }
 
-      options.onOpen?.()
       isConnected.value = true
+      if (!ownsConnection(connectionGeneration, connectionController)) return
+      options.onOpen?.()
+      if (!ownsConnection(connectionGeneration, connectionController)) return
       const reader = response.body.getReader()
       const decoder = new TextDecoder()
       let buffer = ''
 
       for (;;) {
         const { value, done } = await reader.read()
+        if (!ownsConnection(connectionGeneration, connectionController)) return
         if (done) break
         buffer += decoder.decode(value, { stream: true })
 
@@ -727,41 +757,61 @@ export function usePluginEventStream<TData = string>(
         while (boundary !== -1) {
           const block = buffer.slice(0, boundary)
           buffer = buffer.slice(buffer[boundary] === '\r' ? boundary + 4 : boundary + 2)
-          const message = parseSseEvent<TData>(block, options.parseJson === true)
+          const message = parseSseEvent<TData>(block, parseJson)
           if (message) {
             lastMessage.value = message
+            if (!ownsConnection(connectionGeneration, connectionController)) return
             if (message.id !== undefined) {
               lastEventId.value = message.id
+              if (!ownsConnection(connectionGeneration, connectionController)) return
             }
             if (message.retry !== undefined) {
               options.reconnectDelayMs = message.retry
             }
+            if (!ownsConnection(connectionGeneration, connectionController)) return
             options.onMessage?.(message)
+            if (!ownsConnection(connectionGeneration, connectionController)) return
           }
           boundary = buffer.search(/\r?\n\r?\n/)
         }
       }
     } catch (err) {
-      if (!stopped && !(err instanceof DOMException && err.name === 'AbortError')) {
+      if (
+        ownsConnection(connectionGeneration, connectionController)
+        && !(err instanceof DOMException && err.name === 'AbortError')
+      ) {
         const message = err instanceof Error ? err.message : 'Plugin event stream failed'
         error.value = message
-        options.onError?.(err)
+        if (ownsConnection(connectionGeneration, connectionController)) {
+          options.onError?.(err)
+        }
       }
     } finally {
-      isConnecting.value = false
-      isConnected.value = false
-      scheduleReconnect()
+      if (ownsConnection(connectionGeneration, connectionController)) {
+        isConnecting.value = false
+        if (ownsConnection(connectionGeneration, connectionController)) {
+          isConnected.value = false
+          if (ownsConnection(connectionGeneration, connectionController)) {
+            controller = null
+            scheduleReconnect(connectionGeneration)
+          }
+        }
+      }
     }
   }
 
   function start(): void {
+    if (!stopped) return
     stopped = false
     clearReconnectTimer()
-    void connect()
+    generation += 1
+    void connect(generation)
   }
 
   function stop(): void {
+    if (stopped) return
     stopped = true
+    generation += 1
     clearReconnectTimer()
     controller?.abort()
     controller = null

package/src/index.ts

@@ -25,6 +25,9 @@ export * from './permissions'
 // Instrument monitoring
 export * from './instrument'
 
+// Job state helpers
+export * from './jobs'
+
 // LCMS sequence helpers
 export * from './lcms'
 

package/src/jobs.ts

@@ -0,0 +1,75 @@
+import type { JobState, JobStateInput, JobStatus } from './types/jobs'
+
+const ACTIVE_JOB_STATUSES = new Set<JobStatus>([
+  'awaiting_input',
+  'queued',
+  'running',
+])
+const TERMINAL_JOB_STATUSES = new Set<JobStatus>([
+  'completed',
+  'failed',
+  'cancelled',
+])
+
+export interface JobCapabilityInput {
+  status: string
+  can_cancel?: boolean | null
+  can_delete?: boolean | null
+}
+
+export interface JobCapabilities {
+  can_cancel: boolean
+  can_delete: boolean
+}
+
+/** Resolve action support while retaining one-cycle legacy status inference. */
+export function resolveJobCapabilities(job: JobCapabilityInput): JobCapabilities {
+  const legacyCanCancel = job.status === 'queued' || job.status === 'running'
+  const legacyCanDelete = TERMINAL_JOB_STATUSES.has(job.status as JobStatus)
+  return {
+    can_cancel: typeof job.can_cancel === 'boolean' ? job.can_cancel : legacyCanCancel,
+    can_delete: typeof job.can_delete === 'boolean' ? job.can_delete : legacyCanDelete,
+  }
+}
+
+/** Clamp invalid or out-of-range progress values for safe display. */
+export function normalizeJobPercent(value: number): number {
+  if (!Number.isFinite(value)) return 0
+  return Math.min(100, Math.max(0, value))
+}
+
+/** Create a detached canonical state without changing the transport input. */
+export function normalizeJobState(job: JobStateInput): JobState {
+  const capabilities = resolveJobCapabilities(job)
+  return {
+    ...job,
+    progress: {
+      ...job.progress,
+      percent: normalizeJobPercent(job.progress.percent),
+    },
+    warnings: [...job.warnings],
+    folders: [...job.folders],
+    metadata: { ...job.metadata },
+    ...capabilities,
+  }
+}
+
+export function isActiveJobStatus(status: JobStatus): boolean {
+  return ACTIVE_JOB_STATUSES.has(status)
+}
+
+export function isTerminalJobStatus(status: JobStatus): boolean {
+  return TERMINAL_JOB_STATUSES.has(status)
+}
+
+export function jobStatusLabel(status: JobStatus): string {
+  const labels: Record<JobStatus, string> = {
+    awaiting_input: 'Waiting for input',
+    queued: 'Queued',
+    running: 'Running',
+    completed: 'Completed',
+    failed: 'Failed',
+    cancelled: 'Cancelled',
+  }
+  return labels[status]
+}