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

package/src/composables/useExperimentSave.ts

@@ -1,5 +1,22 @@
-import { ref, type Ref } from 'vue'
+import { computed, ref, type ComputedRef, type Ref } from 'vue'
 import { useApi } from './useApi'
+import { useRequestSyncState } from './useRequestSyncState'
+import { createBioTemplatePresetCollection } from '../templates'
+import type {
+  CreateLcmsBatchCollectionOptions,
+  CreateQpcrExpressionCollectionOptions,
+  CreateWellPlateScreenCollectionOptions,
+  TemplatePresetId,
+} from '../templates'
+import {
+  getInjectedPlatformContext,
+  resolveCurrentExperimentId,
+} from './platformContextHelpers'
+
+type TemplatePresetCollectionOptions =
+  | CreateWellPlateScreenCollectionOptions
+  | CreateQpcrExpressionCollectionOptions
+  | CreateLcmsBatchCollectionOptions
 
 export interface UseExperimentSaveOptions {
   /** Default plugin_id for all save/load calls. */
@@ -11,16 +28,39 @@ export interface UseExperimentSaveOptions {
 }
 
 export interface UseExperimentSaveReturn {
+  /** Current experiment id from platform injection, URL query, or URL path. */
+  currentExperimentId: ComputedRef<number | undefined>
+  /** Whether a current experiment id is available. */
+  hasCurrentExperiment: ComputedRef<boolean>
   /** Whether a save operation is in progress. */
   isSaving: Ref<boolean>
+  /** Whether a load or delete operation is in progress. */
+  isLoading: Ref<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>
   /** Timestamp of the last successful save, or null. */
   lastSavedAt: Ref<Date | null>
   /** Save design data for an experiment. */
   saveDesign: (experimentId: number, data: Record<string, unknown>) => Promise<boolean>
+  /** Save design data for the current experiment. */
+  saveCurrentDesign: (data: Record<string, unknown>) => Promise<boolean>
+  /** Create and save a built-in biology template preset as experiment design data. */
+  saveTemplatePreset: (
+    experimentId: number,
+    name: TemplatePresetId | string,
+    options?: TemplatePresetCollectionOptions,
+  ) => Promise<boolean>
+  /** Create and save a built-in biology template preset for the current experiment. */
+  saveCurrentTemplatePreset: (
+    name: TemplatePresetId | string,
+    options?: TemplatePresetCollectionOptions,
+  ) => Promise<boolean>
   /** Save analysis result for an experiment. */
   saveAnalysis: (experimentId: number, result: Record<string, unknown>) => Promise<boolean>
+  /** Save analysis result for the current experiment. */
+  saveCurrentAnalysis: (result: Record<string, unknown>) => Promise<boolean>
   /** Save design and/or analysis in one call. */
   save: (experimentId: number, opts: {
     design?: Record<string, unknown>
@@ -28,28 +68,59 @@ export interface UseExperimentSaveReturn {
   }) => Promise<boolean>
   /** Load design data for an experiment. */
   loadDesign: (experimentId: number) => Promise<Record<string, unknown> | null>
+  /** Load design data for the current experiment. */
+  loadCurrentDesign: () => Promise<Record<string, unknown> | null>
   /** Load analysis result for an experiment. */
   loadAnalysis: (experimentId: number) => Promise<Record<string, unknown> | null>
+  /** Load analysis result for the current experiment. */
+  loadCurrentAnalysis: () => Promise<Record<string, unknown> | null>
   /** Delete design data for an experiment. */
   deleteDesign: (experimentId: number) => Promise<boolean>
+  /** Delete design data for the current experiment. */
+  deleteCurrentDesign: () => Promise<boolean>
   /** Delete analysis result for an experiment. */
   deleteAnalysis: (experimentId: number) => Promise<boolean>
+  /** Delete analysis result for the current experiment. */
+  deleteCurrentAnalysis: () => Promise<boolean>
+  /** Require and return the current experiment id, or throw when missing. */
+  requireCurrentExperimentId: () => number
 }
 
-/** Persists and loads experiment design and analysis data via the plugin's API endpoint. */
+/** Persists experiment design, analysis, and built-in template preset data through the platform API. */
 export function useExperimentSave(
   options: UseExperimentSaveOptions = {},
 ): UseExperimentSaveReturn {
-  const api = useApi({ baseUrl: options.apiBaseUrl })
-  const pluginId = options.pluginId
+  const injectedContext = getInjectedPlatformContext()
+  const api = useApi({ baseUrl: options.apiBaseUrl ?? injectedContext?.platformApiUrl })
+  const pluginId = options.pluginId ?? injectedContext?.plugin?.id
   const schemaVersion = options.schemaVersion ?? '1.0'
+  const currentExperimentId = computed<number | undefined>(() => {
+    return resolveCurrentExperimentId(injectedContext)
+  })
+  const hasCurrentExperiment = computed(() => currentExperimentId.value !== undefined)
 
+  const request = useRequestSyncState('Experiment request failed.')
   const isSaving = ref(false)
-  const error = ref<string | null>(null)
-  const lastSavedAt = ref<Date | null>(null)
+  const isLoading = ref(false)
+  const error = request.error
+  const lastLoadedAt = request.lastLoadedAt
+  const lastSavedAt = request.lastSavedAt
 
-  function setError(e: unknown): void {
-    error.value = e instanceof Error ? e.message : 'Unknown error'
+  function requireCurrentExperimentId(): number {
+    const id = currentExperimentId.value
+    if (id === undefined) {
+      throw new Error('[MINT SDK] No current experiment is selected.')
+    }
+    return id
+  }
+
+  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
   }
 
   async function saveDesign(
@@ -57,78 +128,102 @@ export function useExperimentSave(
     data: Record<string, unknown>,
   ): Promise<boolean> {
     if (!pluginId) {
-      error.value = 'pluginId is required for saveDesign'
+      request.setError('pluginId is required for saveDesign')
       return false
     }
     isSaving.value = true
-    error.value = null
     try {
-      await api.put(`/experiments/${experimentId}/data`, {
-        plugin_id: pluginId,
-        data,
-        schema_version: schemaVersion,
-      })
-      lastSavedAt.value = new Date()
+      await request.run(async () => {
+        await api.put(`/experiments/${experimentId}/data`, {
+          plugin_id: pluginId,
+          data,
+          schema_version: schemaVersion,
+        })
+      }, { success: 'save' })
       return true
-    } catch (e) {
-      setError(e)
+    } catch {
       return false
     } finally {
       isSaving.value = false
     }
   }
 
+  async function saveCurrentDesign(data: Record<string, unknown>): Promise<boolean> {
+    const experimentId = currentExperimentIdOrError('saveDesign')
+    return experimentId === undefined ? false : saveDesign(experimentId, data)
+  }
+
+  async function saveTemplatePreset(
+    experimentId: number,
+    name: TemplatePresetId | string,
+    presetOptions: TemplatePresetCollectionOptions = {},
+  ): Promise<boolean> {
+    const collection = createBioTemplatePresetCollection(name, presetOptions)
+    return saveDesign(experimentId, collection as unknown as Record<string, unknown>)
+  }
+
+  async function saveCurrentTemplatePreset(
+    name: TemplatePresetId | string,
+    presetOptions: TemplatePresetCollectionOptions = {},
+  ): Promise<boolean> {
+    const experimentId = currentExperimentIdOrError('saveTemplatePreset')
+    return experimentId === undefined ? false : saveTemplatePreset(experimentId, name, presetOptions)
+  }
+
   async function saveAnalysis(
     experimentId: number,
     result: Record<string, unknown>,
   ): Promise<boolean> {
     if (!pluginId) {
-      error.value = 'pluginId is required for saveAnalysis'
+      request.setError('pluginId is required for saveAnalysis')
       return false
     }
     isSaving.value = true
-    error.value = null
     try {
-      await api.put(`/experiments/${experimentId}/results/${pluginId}`, {
-        result,
-      })
-      lastSavedAt.value = new Date()
+      await request.run(async () => {
+        await api.put(`/experiments/${experimentId}/results/${pluginId}`, {
+          result,
+        })
+      }, { success: 'save' })
       return true
-    } catch (e) {
-      setError(e)
+    } catch {
       return false
     } finally {
       isSaving.value = false
     }
   }
 
+  async function saveCurrentAnalysis(result: Record<string, unknown>): Promise<boolean> {
+    const experimentId = currentExperimentIdOrError('saveAnalysis')
+    return experimentId === undefined ? false : saveAnalysis(experimentId, result)
+  }
+
   async function save(
     experimentId: number,
     opts: { design?: Record<string, unknown>; analysis?: Record<string, unknown> },
   ): Promise<boolean> {
     if ((opts.design || opts.analysis) && !pluginId) {
-      error.value = 'pluginId is required for save'
+      request.setError('pluginId is required for save')
       return false
     }
     isSaving.value = true
-    error.value = null
     try {
-      if (opts.design) {
-        await api.put(`/experiments/${experimentId}/data`, {
-          plugin_id: pluginId,
-          data: opts.design,
-          schema_version: schemaVersion,
-        })
-      }
-      if (opts.analysis) {
-        await api.put(`/experiments/${experimentId}/results/${pluginId}`, {
-          result: opts.analysis,
-        })
-      }
-      lastSavedAt.value = new Date()
+      await request.run(async () => {
+        if (opts.design) {
+          await api.put(`/experiments/${experimentId}/data`, {
+            plugin_id: pluginId,
+            data: opts.design,
+            schema_version: schemaVersion,
+          })
+        }
+        if (opts.analysis) {
+          await api.put(`/experiments/${experimentId}/results/${pluginId}`, {
+            result: opts.analysis,
+          })
+        }
+      }, { success: 'save' })
       return true
-    } catch (e) {
-      setError(e)
+    } catch {
       return false
     } finally {
       isSaving.value = false
@@ -138,55 +233,112 @@ export function useExperimentSave(
   async function loadDesign(
     experimentId: number,
   ): Promise<Record<string, unknown> | null> {
+    isLoading.value = true
     try {
-      return await api.get<Record<string, unknown>>(`/experiments/${experimentId}/data`)
+      return await request.run(
+        () => api.get<Record<string, unknown>>(`/experiments/${experimentId}/data`),
+        { success: 'load' },
+      )
     } catch {
       return null
+    } finally {
+      isLoading.value = false
     }
   }
 
+  async function loadCurrentDesign(): Promise<Record<string, unknown> | null> {
+    const experimentId = currentExperimentIdOrError('loadDesign')
+    return experimentId === undefined ? null : loadDesign(experimentId)
+  }
+
   async function loadAnalysis(
     experimentId: number,
   ): Promise<Record<string, unknown> | null> {
-    if (!pluginId) return null
+    if (!pluginId) {
+      request.setError('pluginId is required for loadAnalysis')
+      return null
+    }
+    isLoading.value = true
     try {
-      return await api.get<Record<string, unknown>>(
-        `/experiments/${experimentId}/results/${pluginId}`,
+      return await request.run(
+        () => api.get<Record<string, unknown>>(
+          `/experiments/${experimentId}/results/${pluginId}`,
+        ),
+        { success: 'load' },
       )
     } catch {
       return null
+    } finally {
+      isLoading.value = false
     }
   }
 
+  async function loadCurrentAnalysis(): Promise<Record<string, unknown> | null> {
+    const experimentId = currentExperimentIdOrError('loadAnalysis')
+    return experimentId === undefined ? null : loadAnalysis(experimentId)
+  }
+
   async function deleteDesign(experimentId: number): Promise<boolean> {
+    isLoading.value = true
     try {
-      await api.delete(`/experiments/${experimentId}/data`)
+      await request.run(() => api.delete(`/experiments/${experimentId}/data`))
       return true
     } catch {
       return false
+    } finally {
+      isLoading.value = false
     }
   }
 
+  async function deleteCurrentDesign(): Promise<boolean> {
+    const experimentId = currentExperimentIdOrError('deleteDesign')
+    return experimentId === undefined ? false : deleteDesign(experimentId)
+  }
+
   async function deleteAnalysis(experimentId: number): Promise<boolean> {
-    if (!pluginId) return false
+    if (!pluginId) {
+      request.setError('pluginId is required for deleteAnalysis')
+      return false
+    }
+    isLoading.value = true
     try {
-      await api.delete(`/experiments/${experimentId}/results/${pluginId}`)
+      await request.run(() => api.delete(`/experiments/${experimentId}/results/${pluginId}`))
       return true
     } catch {
       return false
+    } finally {
+      isLoading.value = false
     }
   }
 
+  async function deleteCurrentAnalysis(): Promise<boolean> {
+    const experimentId = currentExperimentIdOrError('deleteAnalysis')
+    return experimentId === undefined ? false : deleteAnalysis(experimentId)
+  }
+
   return {
+    currentExperimentId,
+    hasCurrentExperiment,
     isSaving,
+    isLoading,
     error,
+    lastLoadedAt,
     lastSavedAt,
     saveDesign,
+    saveCurrentDesign,
+    saveTemplatePreset,
+    saveCurrentTemplatePreset,
     saveAnalysis,
+    saveCurrentAnalysis,
     save,
     loadDesign,
+    loadCurrentDesign,
     loadAnalysis,
+    loadCurrentAnalysis,
     deleteDesign,
+    deleteCurrentDesign,
     deleteAnalysis,
+    deleteCurrentAnalysis,
+    requireCurrentExperimentId,
   }
 }

package/src/composables/useExperimentSelector.ts

@@ -1,5 +1,7 @@
-import { ref, reactive, computed, watch, onScopeDispose, type Ref, type ComputedRef } from 'vue'
+import { ref, reactive, computed, watch, type Ref, type ComputedRef } from 'vue'
 import { useApi } from './useApi'
+import { useDebouncedWatch } from './useDebouncedWatch'
+import { useRequestSyncState } from './useRequestSyncState'
 import { datePresetToISO } from './experiment-utils'
 import type {
   ExperimentSummary,
@@ -28,27 +30,47 @@ export interface UseExperimentSelectorOptions {
 }
 
 export interface UseExperimentSelectorReturn {
+  /** Current page of fetched experiment rows. */
   experiments: Ref<ExperimentSummary[]>
+  /** Total matching experiment count reported by the platform. */
   total: Ref<number>
+  /** Currently selected experiment, or null. */
   selectedExperiment: Ref<ExperimentSummary | null>
+  /** Mutable filters used for the next fetch. */
   filters: ExperimentFilters
+  /** Whether experiment rows are currently loading. */
   isLoading: Ref<boolean>
+  /** Error message from the last failed fetch, or null. */
   error: Ref<string | null>
+  /** Timestamp of the last successful experiment fetch, or null. */
+  lastLoadedAt: Ref<Date | null>
+  /** Current zero-based page index. */
   page: Ref<number>
+  /** Whether another page can be loaded. */
   hasMore: ComputedRef<boolean>
   // Sort
+  /** Combined sort key in the form `<field>:<asc|desc>`. */
   sortKey: Ref<string>
   // Filter options
+  /** Available experiment type options for filter UI. */
   experimentTypes: Ref<ExperimentTypeOption[]>
+  /** Available project options for filter UI. */
   projects: Ref<SelectOption<string>[]>
   // Grouped view
+  /** Fetched experiments grouped by project name. */
   groupedByProject: ComputedRef<[string, ExperimentSummary[]][]>
   // Methods
+  /** Fetch the current page with the current filters. */
   fetch: () => Promise<void>
+  /** Fetch and append the next page when available. */
   loadMore: () => Promise<void>
+  /** Clear fetched rows and refetch page zero. */
   reset: () => void
+  /** Select an experiment. */
   select: (experiment: ExperimentSummary) => void
+  /** Clear selection and filters. */
   clear: () => void
+  /** Fetch experiment type and project filter options. */
   fetchFilterOptions: () => Promise<void>
 }
 
@@ -63,8 +85,10 @@ export function useExperimentSelector(
   const experiments = ref<ExperimentSummary[]>([])
   const total = ref(0)
   const selectedExperiment = ref<ExperimentSummary | null>(null)
-  const isLoading = ref(false)
-  const error = ref<string | null>(null)
+  const request = useRequestSyncState('Failed to fetch experiments')
+  const isLoading = request.loading
+  const error = request.error
+  const lastLoadedAt = request.lastLoadedAt
   const page = ref(0)
 
   // Sort: combined key like "created_at:desc"
@@ -94,72 +118,69 @@ export function useExperimentSelector(
   }
 
   async function fetchExperiments(): Promise<void> {
-    isLoading.value = true
-    error.value = null
     try {
-      const params = new URLSearchParams()
-      // Priority: explicit option > platform context (single type) > filter dropdown > no filter
-      const allowedTypes = getPlatformContext()?.allowedExperimentTypes
-      const effectiveType = experimentType
-        ?? (allowedTypes?.length === 1 ? allowedTypes[0] : undefined)
-        ?? filters.experimentType
-        ?? undefined
-      if (effectiveType) params.set('experiment_type', effectiveType)
-      if (filters.status) params.set('status', filters.status)
-      if (filters.search) params.set('search', filters.search)
-      if (filters.project) params.set('project', filters.project)
-
-      // Sort params
-      const { sortBy, sortOrder } = parseSortKey()
-      params.set('sort_by', sortBy)
-      params.set('sort_order', sortOrder)
-
-      // Date preset → created_after
-      if (filters.datePreset) {
-        params.set('created_after', datePresetToISO(filters.datePreset))
-      }
+      await request.run(async () => {
+        const params = new URLSearchParams()
+        // Priority: explicit option > platform context (single type) > filter dropdown > no filter
+        const allowedTypes = getPlatformContext()?.allowedExperimentTypes
+        const effectiveType = experimentType
+          ?? (allowedTypes?.length === 1 ? allowedTypes[0] : undefined)
+          ?? filters.experimentType
+          ?? undefined
+        if (effectiveType) params.set('experiment_type', effectiveType)
+        if (filters.status) params.set('status', filters.status)
+        if (filters.search) params.set('search', filters.search)
+        if (filters.project) params.set('project', filters.project)
+
+        // Sort params
+        const { sortBy, sortOrder } = parseSortKey()
+        params.set('sort_by', sortBy)
+        params.set('sort_order', sortOrder)
+
+        // Date preset → created_after
+        if (filters.datePreset) {
+          params.set('created_after', datePresetToISO(filters.datePreset))
+        }
 
-      params.set('limit', String(limit))
-      params.set('skip', String(page.value * limit))
+        params.set('limit', String(limit))
+        params.set('skip', String(page.value * limit))
 
-      const query = params.toString()
-      const base = platformBase ?? ''
-      const url = `${base}/experiments${query ? `?${query}` : ''}`
-      const data = await api.get<ExperimentListResponse>(url)
+        const query = params.toString()
+        const base = platformBase ?? ''
+        const url = `${base}/experiments${query ? `?${query}` : ''}`
+        const data = await api.get<ExperimentListResponse>(url)
 
-      // Client-side filter for multiple allowed types (backend only supports single type)
-      let filtered = data.experiments
-      if (!effectiveType && allowedTypes && allowedTypes.length > 1) {
-        const typeSet = new Set(allowedTypes)
-        filtered = filtered.filter(e => typeSet.has(e.experiment_type))
-      }
+        // Client-side filter for multiple allowed types (backend only supports single type)
+        let filtered = data.experiments
+        if (!effectiveType && allowedTypes && allowedTypes.length > 1) {
+          const typeSet = new Set(allowedTypes)
+          filtered = filtered.filter(e => typeSet.has(e.experiment_type))
+        }
 
-      if (page.value === 0) {
-        experiments.value = filtered
-      } else {
-        experiments.value = [...experiments.value, ...filtered]
-      }
-      // When client-side filtering is active (multiple allowedTypes), we can't
-      // use data.total since it counts all types. Check if server has more pages.
-      if (!effectiveType && allowedTypes && allowedTypes.length > 1) {
-        if (data.experiments.length < limit) {
-          // Server returned less than a full page — no more data
-          total.value = experiments.value.length
+        if (page.value === 0) {
+          experiments.value = filtered
         } else {
-          // Might be more pages on the server
-          total.value = experiments.value.length + 1
+          experiments.value = [...experiments.value, ...filtered]
         }
-      } else {
-        total.value = data.total
-      }
-    } catch (e) {
-      error.value = e instanceof Error ? e.message : 'Failed to fetch experiments'
+        // When client-side filtering is active (multiple allowedTypes), we can't
+        // use data.total since it counts all types. Check if server has more pages.
+        if (!effectiveType && allowedTypes && allowedTypes.length > 1) {
+          if (data.experiments.length < limit) {
+            // Server returned less than a full page — no more data
+            total.value = experiments.value.length
+          } else {
+            // Might be more pages on the server
+            total.value = experiments.value.length + 1
+          }
+        } else {
+          total.value = data.total
+        }
+      }, { success: 'load', errorMessage: 'Failed to fetch experiments' })
+    } catch {
       if (page.value === 0) {
         experiments.value = []
         total.value = 0
       }
-    } finally {
-      isLoading.value = false
     }
   }
 
@@ -215,6 +236,7 @@ export function useExperimentSelector(
     filters.datePreset = undefined
     sortKey.value = 'created_at:desc'
     page.value = 0
+    request.clearError()
   }
 
   // Group experiments by project (client-side)
@@ -237,34 +259,25 @@ export function useExperimentSelector(
     })
   })
 
-  // Debounced watch on search filter
-  let debounceTimer: ReturnType<typeof setTimeout> | null = null
-  watch(
+  const searchWatch = useDebouncedWatch(
     () => filters.search,
     () => {
-      if (debounceTimer) clearTimeout(debounceTimer)
-      debounceTimer = setTimeout(() => {
-        page.value = 0
-        fetchExperiments()
-      }, 300)
+      page.value = 0
+      fetchExperiments()
     },
+    { delay: 300 },
   )
 
   // Immediate watch on discrete filters and sort (cancel any pending search debounce)
   watch(
     () => [filters.status, filters.project, filters.experimentType, filters.datePreset, sortKey.value],
     () => {
-      if (debounceTimer) clearTimeout(debounceTimer)
-      debounceTimer = null
+      searchWatch.cancel()
       page.value = 0
       fetchExperiments()
     },
   )
 
-  onScopeDispose(() => {
-    if (debounceTimer) clearTimeout(debounceTimer)
-  })
-
   if (immediate) {
     fetchExperiments()
   }
@@ -276,6 +289,7 @@ export function useExperimentSelector(
     filters,
     isLoading,
     error,
+    lastLoadedAt,
     page,
     hasMore,
     sortKey,