@morscherlab/mint-sdk 1.2.0-beta.3 → 1.2.0-beta.5

package/src/composables/protocolTemplateCatalog.ts

@@ -0,0 +1,325 @@
+import type { ProtocolStepType } from '../types'
+
+// Parameter definition for step templates
+export interface ParameterDefinition {
+  key: string
+  label: string
+  type: 'number' | 'text' | 'select' | 'concentration' | 'temperature' | 'duration' | 'reagent'
+  unit?: string
+  options?: Array<{ value: string; label: string }>
+  required?: boolean
+  default?: unknown
+  min?: number
+  max?: number
+  placeholder?: string
+}
+
+// Step template definition
+export interface StepTemplate {
+  id: string
+  type: ProtocolStepType
+  name: string
+  description?: string
+  defaultDuration?: number
+  parameters: ParameterDefinition[]
+  isBuiltIn?: boolean
+}
+
+export const BUILT_IN_PROTOCOL_TEMPLATES: StepTemplate[] = [
+  {
+    id: 'builtin-incubation',
+    type: 'incubation',
+    name: 'Incubation',
+    description: 'Incubate samples at specified conditions',
+    defaultDuration: 60,
+    isBuiltIn: true,
+    parameters: [
+      {
+        key: 'temperature',
+        label: 'Temperature',
+        type: 'temperature',
+        unit: '°C',
+        required: true,
+        default: 37,
+        min: -80,
+        max: 100,
+      },
+      {
+        key: 'duration',
+        label: 'Duration',
+        type: 'duration',
+        unit: 'hours',
+        required: true,
+        default: 24,
+        min: 0,
+      },
+      {
+        key: 'co2',
+        label: 'CO2',
+        type: 'number',
+        unit: '%',
+        required: false,
+        default: 5,
+        min: 0,
+        max: 100,
+      },
+      {
+        key: 'humidity',
+        label: 'Humidity',
+        type: 'number',
+        unit: '%',
+        required: false,
+        default: 95,
+        min: 0,
+        max: 100,
+      },
+    ],
+  },
+  {
+    id: 'builtin-wash',
+    type: 'wash',
+    name: 'Wash',
+    description: 'Wash samples with buffer',
+    defaultDuration: 5,
+    isBuiltIn: true,
+    parameters: [
+      {
+        key: 'buffer',
+        label: 'Buffer',
+        type: 'select',
+        required: true,
+        default: 'PBS',
+        options: [
+          { value: 'PBS', label: 'PBS' },
+          { value: 'PBST', label: 'PBST' },
+          { value: 'TBS', label: 'TBS' },
+          { value: 'TBST', label: 'TBST' },
+          { value: 'Water', label: 'Water' },
+          { value: 'Other', label: 'Other' },
+        ],
+      },
+      {
+        key: 'volume',
+        label: 'Volume',
+        type: 'number',
+        unit: 'µL',
+        required: true,
+        default: 200,
+        min: 0,
+      },
+      {
+        key: 'cycles',
+        label: 'Wash Cycles',
+        type: 'number',
+        required: true,
+        default: 3,
+        min: 1,
+        max: 10,
+      },
+    ],
+  },
+  {
+    id: 'builtin-addition',
+    type: 'addition',
+    name: 'Addition',
+    description: 'Add reagent or compound to samples',
+    defaultDuration: 5,
+    isBuiltIn: true,
+    parameters: [
+      {
+        key: 'reagent',
+        label: 'Reagent',
+        type: 'text',
+        required: true,
+        placeholder: 'Enter reagent name',
+      },
+      {
+        key: 'volume',
+        label: 'Volume',
+        type: 'number',
+        unit: 'µL',
+        required: true,
+        default: 100,
+        min: 0,
+      },
+      {
+        key: 'concentration',
+        label: 'Concentration',
+        type: 'concentration',
+        required: false,
+      },
+    ],
+  },
+  {
+    id: 'builtin-measurement',
+    type: 'measurement',
+    name: 'Measurement',
+    description: 'Take measurements using specified instrument',
+    defaultDuration: 15,
+    isBuiltIn: true,
+    parameters: [
+      {
+        key: 'instrument',
+        label: 'Instrument',
+        type: 'select',
+        required: true,
+        options: [
+          { value: 'plate_reader', label: 'Plate Reader' },
+          { value: 'microscope', label: 'Microscope' },
+          { value: 'flow_cytometer', label: 'Flow Cytometer' },
+          { value: 'spectrophotometer', label: 'Spectrophotometer' },
+          { value: 'other', label: 'Other' },
+        ],
+      },
+      {
+        key: 'readout',
+        label: 'Readout Type',
+        type: 'text',
+        required: false,
+        placeholder: 'e.g., Absorbance 450nm',
+      },
+      {
+        key: 'notes',
+        label: 'Parameters',
+        type: 'text',
+        required: false,
+        placeholder: 'Additional parameters',
+      },
+    ],
+  },
+  {
+    id: 'builtin-centrifuge',
+    type: 'centrifuge',
+    name: 'Centrifuge',
+    description: 'Centrifuge samples',
+    defaultDuration: 10,
+    isBuiltIn: true,
+    parameters: [
+      {
+        key: 'speed',
+        label: 'Speed',
+        type: 'number',
+        unit: 'RPM',
+        required: true,
+        default: 1000,
+        min: 100,
+        max: 20000,
+      },
+      {
+        key: 'duration',
+        label: 'Duration',
+        type: 'number',
+        unit: 'min',
+        required: true,
+        default: 5,
+        min: 1,
+      },
+      {
+        key: 'temperature',
+        label: 'Temperature',
+        type: 'temperature',
+        unit: '°C',
+        required: false,
+        default: 4,
+        min: -10,
+        max: 40,
+      },
+    ],
+  },
+  {
+    id: 'builtin-transfer',
+    type: 'transfer',
+    name: 'Transfer',
+    description: 'Transfer samples between containers',
+    defaultDuration: 10,
+    isBuiltIn: true,
+    parameters: [
+      {
+        key: 'source',
+        label: 'Source',
+        type: 'text',
+        required: true,
+        placeholder: 'Source container',
+      },
+      {
+        key: 'destination',
+        label: 'Destination',
+        type: 'text',
+        required: true,
+        placeholder: 'Destination container',
+      },
+      {
+        key: 'volume',
+        label: 'Volume',
+        type: 'number',
+        unit: 'µL',
+        required: true,
+        default: 100,
+        min: 0,
+      },
+    ],
+  },
+  {
+    id: 'builtin-mix',
+    type: 'mix',
+    name: 'Mix',
+    description: 'Mix samples',
+    defaultDuration: 5,
+    isBuiltIn: true,
+    parameters: [
+      {
+        key: 'method',
+        label: 'Method',
+        type: 'select',
+        required: true,
+        default: 'pipette',
+        options: [
+          { value: 'pipette', label: 'Pipette mixing' },
+          { value: 'vortex', label: 'Vortex' },
+          { value: 'shaker', label: 'Orbital shaker' },
+          { value: 'inversion', label: 'Inversion' },
+        ],
+      },
+      {
+        key: 'duration',
+        label: 'Duration',
+        type: 'number',
+        unit: 'sec',
+        required: false,
+        default: 30,
+        min: 1,
+      },
+      {
+        key: 'speed',
+        label: 'Speed/Intensity',
+        type: 'text',
+        required: false,
+        placeholder: 'e.g., 300 RPM',
+      },
+    ],
+  },
+  {
+    id: 'builtin-custom',
+    type: 'custom',
+    name: 'Custom Step',
+    description: 'Custom protocol step',
+    defaultDuration: 15,
+    isBuiltIn: true,
+    parameters: [
+      {
+        key: 'description',
+        label: 'Description',
+        type: 'text',
+        required: true,
+        placeholder: 'Describe the step',
+      },
+      {
+        key: 'notes',
+        label: 'Notes',
+        type: 'text',
+        required: false,
+        placeholder: 'Additional notes',
+      },
+    ],
+  },
+]

package/src/composables/useAnalysisArtifacts.ts

@@ -0,0 +1,361 @@
+import {
+  computed,
+  ref,
+  toValue,
+  watch,
+  type ComputedRef,
+  type MaybeRefOrGetter,
+  type Ref,
+} from 'vue'
+import { useApi } from './useApi'
+import { useRequestSyncState } from './useRequestSyncState'
+import {
+  getInjectedPlatformContext,
+  resolveCurrentExperimentId,
+} from './platformContextHelpers'
+import type {
+  AnalysisArtifactDetail,
+  AnalysisArtifactListResponse,
+  AnalysisArtifactMetadataUpdate,
+  AnalysisArtifactStatusFilter,
+  AnalysisArtifactSummary,
+  AnalysisArtifactTarget,
+} from '../types/analysisArtifactTypes'
+
+export { ANALYSIS_FILE_ARTIFACT_SCHEMA } from '../types/analysisArtifactTypes'
+
+export interface UseAnalysisArtifactsOptions {
+  /** Experiment id; defaults to platform injection or URL. Refetches when it changes. */
+  experimentId?: MaybeRefOrGetter<number | undefined>
+  /** Override API base URL. */
+  apiBaseUrl?: string
+  /** Scope to a single owning plugin; omit or null to keep all plugins. */
+  pluginId?: MaybeRefOrGetter<string | null | undefined>
+  /** Always request archived artifacts alongside active ones. */
+  includeArchived?: MaybeRefOrGetter<boolean | undefined>
+  /** Fetch as soon as an experiment id is available. */
+  immediate?: boolean
+}
+
+export interface UseAnalysisArtifactsReturn {
+  /** Fetched artifacts, scoped to pluginId when set. */
+  artifacts: ComputedRef<AnalysisArtifactSummary[]>
+  /** Artifacts after applying statusFilter, pluginFilter, and search. */
+  visibleArtifacts: ComputedRef<AnalysisArtifactSummary[]>
+  /** Detail loaded by the last successful getDetail call, or null. */
+  selectedDetail: Ref<AnalysisArtifactDetail | null>
+  /** Resolved experiment id from options, platform injection, or URL. */
+  currentExperimentId: ComputedRef<number | undefined>
+  /** Whether an experiment id is available. */
+  hasCurrentExperiment: ComputedRef<boolean>
+  /** Whether any list or detail fetch is in progress. */
+  isLoading: ComputedRef<boolean>
+  /** Whether any archive/restore/metadata mutation is in progress. */
+  isMutating: ComputedRef<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>
+  /** Case-insensitive filter over display_name and artifact_key. */
+  search: Ref<string>
+  /** Lifecycle filter; widening past "active" refetches with include_archived. */
+  statusFilter: Ref<AnalysisArtifactStatusFilter>
+  /** Plugin filter applied to visibleArtifacts, or null for all plugins. */
+  pluginFilter: Ref<string | null>
+  /** Fetch the artifact list for the current experiment. */
+  list: () => Promise<AnalysisArtifactSummary[]>
+  /** Alias of list. */
+  refresh: () => Promise<AnalysisArtifactSummary[]>
+  /** Fetch one artifact with its result payload; null when it fails or is superseded. */
+  getDetail: (artifactId: number) => Promise<AnalysisArtifactDetail | null>
+  /** Resolve and fetch the exact stable artifact identity. */
+  resolveTarget: (target: AnalysisArtifactTarget) => Promise<AnalysisArtifactDetail | null>
+  /** Update display_name and/or note; resolves to the updated summary or null. */
+  updateMetadata: (
+    artifactId: number,
+    updates: AnalysisArtifactMetadataUpdate,
+  ) => Promise<AnalysisArtifactSummary | null>
+  /** Archive an artifact; resolves to the updated summary or null. */
+  archive: (artifactId: number) => Promise<AnalysisArtifactSummary | null>
+  /** Restore an archived artifact; resolves to the updated summary or null. */
+  restore: (artifactId: number) => Promise<AnalysisArtifactSummary | null>
+  /** Whether a key exists in the loaded artifacts (no network call). */
+  hasArtifactKey: (artifactKey: string) => boolean
+  /** Reset artifacts, selection, and error. */
+  clear: () => void
+}
+
+/**
+ * Lists and manages analysis artifacts through the user-facing platform API.
+ *
+ * @example Recommended
+ * ```ts
+ * const artifacts = useAnalysisArtifacts({ pluginId: 'LEAF' })
+ * await artifacts.list()
+ * ```
+ */
+export function useAnalysisArtifacts(
+  options: UseAnalysisArtifactsOptions = {},
+): UseAnalysisArtifactsReturn {
+  const injectedContext = getInjectedPlatformContext()
+  const api = useApi({ baseUrl: options.apiBaseUrl ?? injectedContext?.platformApiUrl })
+
+  const currentExperimentId = computed<number | undefined>(
+    () => toValue(options.experimentId) ?? resolveCurrentExperimentId(injectedContext),
+  )
+  const hasCurrentExperiment = computed(() => currentExperimentId.value !== undefined)
+  const scopePluginId = computed(() => toValue(options.pluginId) ?? null)
+
+  const request = useRequestSyncState('Analysis artifact request failed.')
+  const fetchedArtifacts = ref<AnalysisArtifactSummary[]>([])
+  const selectedDetail = ref<AnalysisArtifactDetail | null>(null)
+
+  // Counters, not booleans: overlapping requests must not clear each other's flag.
+  const loadingCount = ref(0)
+  const mutatingCount = ref(0)
+  const isLoading = computed(() => loadingCount.value > 0)
+  const isMutating = computed(() => mutatingCount.value > 0)
+
+  const search = ref('')
+  const statusFilter = ref<AnalysisArtifactStatusFilter>('active')
+  const pluginFilter = ref<string | null>(null)
+
+  const needsArchived = computed(
+    () => Boolean(toValue(options.includeArchived)) || statusFilter.value !== 'active',
+  )
+
+  const artifacts = computed(() => (
+    scopePluginId.value
+      ? fetchedArtifacts.value.filter((artifact) => artifact.plugin_id === scopePluginId.value)
+      : fetchedArtifacts.value
+  ))
+
+  const visibleArtifacts = computed(() => {
+    const query = search.value.trim().toLowerCase()
+    return artifacts.value.filter((artifact) => {
+      if (statusFilter.value !== 'all' && artifact.status !== statusFilter.value) return false
+      if (pluginFilter.value && artifact.plugin_id !== pluginFilter.value) return false
+      if (!query) return true
+      return (
+        artifact.display_name.toLowerCase().includes(query)
+        || artifact.artifact_key.toLowerCase().includes(query)
+      )
+    })
+  })
+
+  // Generation tokens: a superseded response must commit nothing — not rows, not the
+  // shared error, not lastLoadedAt — or a late failure would bury fresh results.
+  let listToken = 0
+  let detailToken = 0
+  const hasRequestedList = ref(false)
+
+  function currentExperimentIdOrError(action: string): number | undefined {
+    const id = currentExperimentId.value
+    if (id === undefined) {
+      request.setError(`No current experiment is selected for ${action}`)
+      return undefined
+    }
+    return id
+  }
+
+  function replaceArtifact(summary: AnalysisArtifactSummary): void {
+    const index = fetchedArtifacts.value.findIndex((artifact) => artifact.id === summary.id)
+    if (index >= 0) {
+      fetchedArtifacts.value.splice(index, 1, summary)
+    }
+  }
+
+  async function list(): Promise<AnalysisArtifactSummary[]> {
+    const experimentId = currentExperimentIdOrError('listing analysis artifacts')
+    if (experimentId === undefined) {
+      fetchedArtifacts.value = []
+      return []
+    }
+    const token = ++listToken
+    hasRequestedList.value = true
+    loadingCount.value += 1
+    request.clearError()
+    try {
+      const data = await api.get<AnalysisArtifactListResponse>(
+        `/experiments/${experimentId}/analysis-artifacts?include_archived=${needsArchived.value}`,
+      )
+      if (token !== listToken) return artifacts.value
+      // Copy: replaceArtifact splices in place, and the response array is not ours.
+      fetchedArtifacts.value = [...(data?.artifacts ?? [])]
+      request.markLoaded()
+      return artifacts.value
+    } catch (err) {
+      if (token !== listToken) return []
+      request.setError(err)
+      fetchedArtifacts.value = []
+      return []
+    } finally {
+      loadingCount.value -= 1
+    }
+  }
+
+  async function getDetail(artifactId: number): Promise<AnalysisArtifactDetail | null> {
+    const experimentId = currentExperimentIdOrError('loading an analysis artifact')
+    if (experimentId === undefined) return null
+    const token = ++detailToken
+    loadingCount.value += 1
+    request.clearError()
+    try {
+      const detail = await api.get<AnalysisArtifactDetail>(
+        `/experiments/${experimentId}/analysis-artifacts/${artifactId}`,
+      )
+      if (token !== detailToken) return null
+      selectedDetail.value = detail
+      request.markLoaded()
+      return detail
+    } catch (err) {
+      if (token !== detailToken) return null
+      request.setError(err)
+      return null
+    } finally {
+      loadingCount.value -= 1
+    }
+  }
+
+  async function resolveTarget(
+    target: AnalysisArtifactTarget,
+  ): Promise<AnalysisArtifactDetail | null> {
+    const experimentId = currentExperimentId.value
+    if (experimentId !== target.experimentId) {
+      request.setError(
+        `Analysis artifact target belongs to experiment ${target.experimentId}, not `
+        + `${experimentId ?? 'the current selection'}.`,
+      )
+      return null
+    }
+
+    const available = await list()
+    const summary = available.find((artifact) => (
+      artifact.plugin_id === target.artifactPluginId
+      && artifact.artifact_key === target.artifactKey
+      && artifact.status === 'active'
+    ))
+    if (!summary) {
+      request.setError(
+        `Analysis artifact ${target.artifactPluginId}/${target.artifactKey} is not available.`,
+      )
+      return null
+    }
+
+    const detail = await getDetail(summary.id)
+    if (
+      detail
+      && (
+        detail.experiment_id !== target.experimentId
+        || detail.plugin_id !== target.artifactPluginId
+        || detail.artifact_key !== target.artifactKey
+      )
+    ) {
+      selectedDetail.value = null
+      request.setError(
+        `Analysis artifact ${target.artifactPluginId}/${target.artifactKey} did not `
+        + 'match the requested identity.',
+      )
+      return null
+    }
+    return detail
+  }
+
+  async function mutate(
+    action: string,
+    operation: (experimentId: number) => Promise<AnalysisArtifactSummary>,
+  ): Promise<AnalysisArtifactSummary | null> {
+    const experimentId = currentExperimentIdOrError(action)
+    if (experimentId === undefined) return null
+    mutatingCount.value += 1
+    request.clearError()
+    try {
+      const summary = await operation(experimentId)
+      replaceArtifact(summary)
+      request.markSaved()
+      return summary
+    } catch (err) {
+      request.setError(err)
+      return null
+    } finally {
+      mutatingCount.value -= 1
+    }
+  }
+
+  async function updateMetadata(
+    artifactId: number,
+    updates: AnalysisArtifactMetadataUpdate,
+  ): Promise<AnalysisArtifactSummary | null> {
+    return mutate('updating artifact metadata', (experimentId) =>
+      api.patch<AnalysisArtifactSummary>(
+        `/experiments/${experimentId}/analysis-artifacts/${artifactId}`,
+        updates,
+      ))
+  }
+
+  async function archive(artifactId: number): Promise<AnalysisArtifactSummary | null> {
+    return mutate('archiving an analysis artifact', (experimentId) =>
+      api.post<AnalysisArtifactSummary>(
+        `/experiments/${experimentId}/analysis-artifacts/${artifactId}/archive`,
+      ))
+  }
+
+  async function restore(artifactId: number): Promise<AnalysisArtifactSummary | null> {
+    return mutate('restoring an analysis artifact', (experimentId) =>
+      api.post<AnalysisArtifactSummary>(
+        `/experiments/${experimentId}/analysis-artifacts/${artifactId}/restore`,
+      ))
+  }
+
+  function hasArtifactKey(artifactKey: string): boolean {
+    return artifacts.value.some((artifact) => artifact.artifact_key === artifactKey)
+  }
+
+  /** Drop experiment-scoped state and orphan every in-flight response. */
+  function clear(): void {
+    listToken += 1
+    detailToken += 1
+    fetchedArtifacts.value = []
+    selectedDetail.value = null
+    request.clearError()
+  }
+
+  // Refetch when the scope changes or archived rows are newly needed. `immediate`
+  // covers a late-resolving experiment id; otherwise stay quiet until something
+  // has asked for a list at least once.
+  watch([currentExperimentId, needsArchived], ([experimentId], [previousExperimentId]) => {
+    if (experimentId !== previousExperimentId) {
+      // Scope changed: the previous experiment's rows and any in-flight reply for
+      // them must not survive into the new one.
+      clear()
+    }
+    if (experimentId === undefined) return
+    if (options.immediate || hasRequestedList.value) {
+      void list()
+    }
+  }, { immediate: options.immediate })
+
+  return {
+    artifacts,
+    visibleArtifacts,
+    selectedDetail,
+    currentExperimentId,
+    hasCurrentExperiment,
+    isLoading,
+    isMutating,
+    error: request.error,
+    lastLoadedAt: request.lastLoadedAt,
+    search,
+    statusFilter,
+    pluginFilter,
+    list,
+    refresh: list,
+    getDetail,
+    resolveTarget,
+    updateMetadata,
+    archive,
+    restore,
+    hasArtifactKey,
+    clear,
+  }
+}