@morscherlab/mint-sdk 1.0.61 → 1.0.63

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morscherlab/mint-sdk",
-  "version": "1.0.61",
+  "version": "1.0.63",
   "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__/composables/analysisArtifactTarget.test.ts

@@ -0,0 +1,77 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import {
+  buildAnalysisArtifactTargetQuery,
+  parseAnalysisArtifactTarget,
+} from '../../composables/analysisArtifactTarget'
+import {
+  currentExperimentIdFromUrl,
+  resolveCurrentPluginId,
+} from '../../composables/platformContextHelpers'
+
+describe('analysis artifact target', () => {
+  afterEach(() => {
+    delete (window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__
+    vi.unstubAllGlobals()
+  })
+
+  it('should resolve the canonical injected plugin id', () => {
+    ;(window as unknown as { __MINT_PLATFORM__: unknown }).__MINT_PLATFORM__ = {
+      isIntegrated: true,
+      plugin: { id: 'LEAF', name: 'Leaf UI' },
+      theme: 'system',
+    }
+
+    expect(resolveCurrentPluginId()).toBe('LEAF')
+  })
+
+  it('should tolerate a host that provides a partial location object', () => {
+    vi.stubGlobal('window', {
+      location: { search: '' },
+    })
+
+    expect(currentExperimentIdFromUrl()).toBeUndefined()
+  })
+
+  it('should build the canonical readable query when an artifact id hint is present', () => {
+    const query = buildAnalysisArtifactTargetQuery({
+      experimentId: 66,
+      artifactPluginId: 'LEAF',
+      artifactKey: 'exp316_260703_ys_rna_ide_scr',
+      artifactId: 206,
+    })
+
+    expect(query.toString()).toBe(
+      'experiment_id=66&artifact_plugin_id=LEAF'
+      + '&artifact_key=exp316_260703_ys_rna_ide_scr&artifact_id=206',
+    )
+  })
+
+  it('should parse the canonical identity without requiring an artifact id hint', () => {
+    const target = parseAnalysisArtifactTarget(new URLSearchParams(
+      'experiment_id=66&artifact_plugin_id=LEAF&artifact_key=result',
+    ))
+
+    expect(target).toEqual({
+      experimentId: 66,
+      artifactPluginId: 'LEAF',
+      artifactKey: 'result',
+    })
+  })
+
+  it('should reject an incomplete target instead of guessing another artifact', () => {
+    const target = parseAnalysisArtifactTarget(new URLSearchParams(
+      'experiment_id=66&artifact_key=result',
+    ))
+
+    expect(target).toBeNull()
+  })
+
+  it('should reject non-positive numeric identifiers', () => {
+    const target = parseAnalysisArtifactTarget(new URLSearchParams(
+      'experiment_id=0&artifact_plugin_id=LEAF&artifact_key=result&artifact_id=-1',
+    ))
+
+    expect(target).toBeNull()
+  })
+})

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

@@ -19,7 +19,10 @@ vi.mock('../../composables/useApi', () => ({
 }))
 
 import { useAnalysisArtifacts } from '../../composables/useAnalysisArtifacts'
-import type { AnalysisArtifactSummary } from '../../types/analysisArtifactTypes'
+import type {
+  AnalysisArtifactDetail,
+  AnalysisArtifactSummary,
+} from '../../types/analysisArtifactTypes'
 
 // ---------------------------------------------------------------------------
 // Fixtures
@@ -177,6 +180,76 @@ describe('useAnalysisArtifacts', () => {
     })
   })
 
+  describe('resolveTarget', () => {
+    it('should resolve the exact stable identity when the numeric hint is stale', async () => {
+      const detail = {
+        ...makeArtifact({
+          id: 2,
+          experiment_id: 42,
+          plugin_id: 'plugin-b',
+          artifact_key: 'peaks',
+        }),
+        result: { schema_version: 'mint.analysis_file.v1' },
+        tree: [],
+        summary: null,
+      } satisfies AnalysisArtifactDetail
+      mockGet
+        .mockResolvedValueOnce({ artifacts: ARTIFACTS })
+        .mockResolvedValueOnce(detail)
+      const { resolveTarget } = setup()
+
+      const resolved = await resolveTarget({
+        experimentId: 42,
+        artifactPluginId: 'plugin-b',
+        artifactKey: 'peaks',
+        artifactId: 999,
+      })
+
+      expect({
+        resolvedId: resolved?.id,
+        detailPath: mockGet.mock.calls[1]?.[0],
+      }).toEqual({
+        resolvedId: 2,
+        detailPath: '/experiments/42/analysis-artifacts/2',
+      })
+    })
+
+    it('should fail explicitly when the stable identity is not available', async () => {
+      const { resolveTarget, error } = setup()
+
+      const resolved = await resolveTarget({
+        experimentId: 42,
+        artifactPluginId: 'LEAF',
+        artifactKey: 'missing',
+      })
+
+      expect({ resolved, error: error.value }).toEqual({
+        resolved: null,
+        error: 'Analysis artifact LEAF/missing is not available.',
+      })
+    })
+
+    it('should reject a target from another experiment before making a request', async () => {
+      const { resolveTarget, error } = setup()
+
+      const resolved = await resolveTarget({
+        experimentId: 66,
+        artifactPluginId: 'LEAF',
+        artifactKey: 'result',
+      })
+
+      expect({
+        resolved,
+        error: error.value,
+        requests: mockGet.mock.calls,
+      }).toEqual({
+        resolved: null,
+        error: 'Analysis artifact target belongs to experiment 66, not 42.',
+        requests: [],
+      })
+    })
+  })
+
   // -------------------------------------------------------------------------
   // experiment id resolution
   // -------------------------------------------------------------------------

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

@@ -62,8 +62,10 @@ function pendingEventStreamResponse(): {
 describe('usePluginClient', () => {
   let requestConfigs: AxiosRequestConfig[] = []
   let requestBodies: unknown[] = []
+  let requestMethods: string[] = []
   let nextGetError: Error | null = null
   let nextGetData: unknown
+  let nextPostData: unknown
   let nextPatchData: unknown
   let nextPutData: unknown
 
@@ -71,8 +73,10 @@ describe('usePluginClient', () => {
     setActivePinia(createPinia())
     requestConfigs = []
     requestBodies = []
+    requestMethods = []
     nextGetError = null
     nextGetData = undefined
+    nextPostData = undefined
     nextPatchData = undefined
     nextPutData = undefined
     vi.spyOn(axios.Axios.prototype, 'get').mockImplementation(async function (
@@ -80,6 +84,7 @@ describe('usePluginClient', () => {
       url: string,
       config?: AxiosRequestConfig,
     ) {
+      requestMethods.push('get')
       requestConfigs.push({ url, ...config })
       if (nextGetError) throw nextGetError
       return { data: nextGetData ?? { called: url } }
@@ -90,9 +95,10 @@ describe('usePluginClient', () => {
       data?: unknown,
       config?: AxiosRequestConfig,
     ) {
+      requestMethods.push('post')
       requestConfigs.push({ url, ...config })
       requestBodies.push(data)
-      return { data: { called: url } }
+      return { data: nextPostData ?? { called: url } }
     })
     vi.spyOn(axios.Axios.prototype, 'patch').mockImplementation(async function (
       this: unknown,
@@ -100,6 +106,7 @@ describe('usePluginClient', () => {
       data?: unknown,
       config?: AxiosRequestConfig,
     ) {
+      requestMethods.push('patch')
       requestConfigs.push({ url, ...config })
       requestBodies.push(data)
       return { data: nextPatchData ?? { called: url } }
@@ -110,6 +117,7 @@ describe('usePluginClient', () => {
       data?: unknown,
       config?: AxiosRequestConfig,
     ) {
+      requestMethods.push('put')
       requestConfigs.push({ url, ...config })
       requestBodies.push(data)
       return { data: nextPutData ?? { called: url } }
@@ -119,6 +127,7 @@ describe('usePluginClient', () => {
       url: string,
       config?: AxiosRequestConfig,
     ) {
+      requestMethods.push('delete')
       requestConfigs.push({ url, ...config })
       requestBodies.push(config?.data)
       return { data: { called: url } }
@@ -410,6 +419,91 @@ describe('usePluginClient', () => {
     expect(requestConfigs[0]!.responseType).toBe('blob')
   })
 
+  it('downloads generated POST endpoint blobs with the contract body and request options', async () => {
+    const expectedBlob = new Blob(['zip'])
+    const controller = new AbortController()
+    nextPostData = expectedBlob
+
+    const blob = await downloadPluginEndpoint(
+      contract,
+      {
+        method: 'post',
+        path: '/export/{sessionId}/results',
+        pathParams: ['sessionId'],
+        queryParams: [
+          { name: 'revision', fieldName: 'revision', type: 'number', required: true },
+        ],
+        hasBody: true,
+        requestContentType: 'application/json',
+      },
+      {
+        sessionId: 'session-1',
+        revision: 4,
+        body: { format: 'wide', correction: false },
+      },
+      { signal: controller.signal },
+    )
+
+    expect({
+      blob,
+      body: requestBodies[0],
+      url: requestConfigs[0]!.url,
+      params: requestConfigs[0]!.params,
+      signal: requestConfigs[0]!.signal,
+      responseType: requestConfigs[0]!.responseType,
+      method: requestMethods[0],
+    }).toEqual({
+      blob: expectedBlob,
+      body: { format: 'wide', correction: false },
+      url: '/export/session-1/results',
+      params: { revision: 4 },
+      signal: controller.signal,
+      responseType: 'blob',
+      method: 'post',
+    })
+  })
+
+  it.each(['put', 'patch', 'delete'] as const)(
+    'downloads generated %s endpoint blobs with the contract body',
+    async (method) => {
+      await downloadPluginEndpoint(
+        contract,
+        {
+          method,
+          path: '/exports/{exportId}',
+          pathParams: ['exportId'],
+          hasBody: true,
+        },
+        { exportId: 'export-1', body: { format: 'wide' } },
+      )
+
+      expect({
+        body: requestBodies[0],
+        method: requestMethods[0],
+        responseType: requestConfigs[0]!.responseType,
+        url: requestConfigs[0]!.url,
+      }).toEqual({
+        body: { format: 'wide' },
+        method,
+        responseType: 'blob',
+        url: '/exports/export-1',
+      })
+    },
+  )
+
+  it('rejects multipart download request bodies', async () => {
+    await expect(downloadPluginEndpoint(
+      contract,
+      {
+        method: 'post',
+        path: '/exports',
+        hasBody: true,
+        requestContentType: 'multipart/form-data',
+      },
+      { body: { format: 'wide' } },
+    )).rejects.toThrow('Plugin download endpoints do not support multipart request bodies')
+  })
+
   it.each([
     new Blob(['chunk']),
     new Uint8Array([1, 2, 3]),

package/src/composables/analysisArtifactTarget.ts

@@ -0,0 +1,53 @@
+import type { AnalysisArtifactTarget } from '../types/analysisArtifactTypes'
+
+const EXPERIMENT_ID = 'experiment_id'
+const ARTIFACT_PLUGIN_ID = 'artifact_plugin_id'
+const ARTIFACT_KEY = 'artifact_key'
+const ARTIFACT_ID = 'artifact_id'
+
+function parsePositiveInteger(value: string | null): number | undefined {
+  if (value === null || !/^\d+$/.test(value)) return undefined
+  const parsed = Number(value)
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined
+}
+
+/** Build the canonical query used to open one analysis artifact in a plugin. */
+export function buildAnalysisArtifactTargetQuery(
+  target: AnalysisArtifactTarget,
+): URLSearchParams {
+  const query = new URLSearchParams()
+  query.set(EXPERIMENT_ID, String(target.experimentId))
+  query.set(ARTIFACT_PLUGIN_ID, target.artifactPluginId)
+  query.set(ARTIFACT_KEY, target.artifactKey)
+  if (target.artifactId !== undefined) {
+    query.set(ARTIFACT_ID, String(target.artifactId))
+  }
+  return query
+}
+
+/** Parse a complete canonical target. Incomplete or invalid input is not guessed. */
+export function parseAnalysisArtifactTarget(
+  query: URLSearchParams,
+): AnalysisArtifactTarget | null {
+  const experimentId = parsePositiveInteger(query.get(EXPERIMENT_ID))
+  const artifactPluginId = query.get(ARTIFACT_PLUGIN_ID)?.trim()
+  const artifactKey = query.get(ARTIFACT_KEY)?.trim()
+  const rawArtifactId = query.get(ARTIFACT_ID)
+  const artifactId = parsePositiveInteger(rawArtifactId)
+
+  if (
+    experimentId === undefined
+    || !artifactPluginId
+    || !artifactKey
+    || (rawArtifactId !== null && artifactId === undefined)
+  ) {
+    return null
+  }
+
+  return {
+    experimentId,
+    artifactPluginId,
+    artifactKey,
+    ...(artifactId === undefined ? {} : { artifactId }),
+  }
+}

package/src/composables/index.ts

@@ -147,6 +147,11 @@ export {
   type UseAnalysisArtifactsOptions,
   type UseAnalysisArtifactsReturn,
 } from './useAnalysisArtifacts'
+export {
+  buildAnalysisArtifactTargetQuery,
+  parseAnalysisArtifactTarget,
+} from './analysisArtifactTarget'
+export { resolveCurrentPluginId } from './platformContextHelpers'
 export {
   formatExperimentDate,
   formatExperimentStatus,

package/src/composables/platformContextHelpers.ts

@@ -12,6 +12,12 @@ export function getInjectedPlatformContext(): PlatformContext | undefined {
   return (window as unknown as { __MINT_PLATFORM__?: PlatformContext }).__MINT_PLATFORM__
 }
 
+/** Return the platform's canonical plugin identity for the mounted frontend. */
+export function resolveCurrentPluginId(): string | undefined {
+  const pluginId = getInjectedPlatformContext()?.plugin?.id
+  return typeof pluginId === 'string' && pluginId ? pluginId : undefined
+}
+
 export function getInjectedExperimentContext(): ExperimentAwarePlatformContext | undefined {
   return getInjectedPlatformContext() as ExperimentAwarePlatformContext | undefined
 }
@@ -38,10 +44,11 @@ export function currentExperimentIdFromContext(
 
 export function currentExperimentIdFromUrl(): number | undefined {
   if (typeof window === 'undefined') return undefined
-  const params = new URLSearchParams(window.location.search)
+  const location = window.location
+  const params = new URLSearchParams(location?.search ?? '')
   return parseExperimentId(params.get('experimentId') ?? params.get('experiment_id'))
-    ?? experimentIdFromPath(window.location.pathname)
-    ?? experimentIdFromPath(window.location.hash.replace(/^#\/?/, '/'))
+    ?? experimentIdFromPath(location?.pathname ?? '')
+    ?? experimentIdFromPath((location?.hash ?? '').replace(/^#\/?/, '/'))
 }
 
 export function resolveCurrentExperimentId(

package/src/composables/useAnalysisArtifacts.ts

@@ -19,6 +19,7 @@ import type {
   AnalysisArtifactMetadataUpdate,
   AnalysisArtifactStatusFilter,
   AnalysisArtifactSummary,
+  AnalysisArtifactTarget,
 } from '../types/analysisArtifactTypes'
 
 export { ANALYSIS_FILE_ARTIFACT_SCHEMA } from '../types/analysisArtifactTypes'
@@ -67,6 +68,8 @@ export interface UseAnalysisArtifactsReturn {
   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,
@@ -206,6 +209,50 @@ export function useAnalysisArtifacts(
     }
   }
 
+  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>,
@@ -296,6 +343,7 @@ export function useAnalysisArtifacts(
     list,
     refresh: list,
     getDetail,
+    resolveTarget,
     updateMetadata,
     archive,
     restore,

package/src/composables/usePluginClient.ts

@@ -486,13 +486,29 @@ export async function downloadPluginEndpoint(
   payload?: unknown,
   options: DownloadPluginEndpointOptions = {},
 ): Promise<Blob> {
+  if (endpoint.requestContentType === MULTIPART_FORM_DATA) {
+    throw new Error('[MINT SDK] Plugin download endpoints do not support multipart request bodies')
+  }
+
   const parts = pluginEndpointRequestParts(contract, endpoint, payload, options.baseUrl)
   const api = useApi({ baseUrl: parts.baseUrl })
-  const blob = await api.get<Blob>(parts.path, {
-    ...(queryConfig(parts.query) ?? {}),
-    ...(options.signal ? { signal: options.signal } : {}),
-    responseType: 'blob',
-  })
+  const config = {
+    ...(endpointRequestConfig(endpoint, parts.query, { signal: options.signal }) ?? {}),
+    responseType: 'blob' as const,
+  }
+  const rawBody = requestBodyFromPayload(payload, parts.requestPayload, endpoint)
+  const body = rawBody === undefined ? undefined : endpointRequestBody(endpoint, rawBody)
+  let blob: Blob
+
+  if (endpoint.method === 'get') blob = await api.get<Blob>(parts.path, config)
+  else if (endpoint.method === 'post') blob = await api.post<Blob>(parts.path, body, config)
+  else if (endpoint.method === 'put') blob = await api.put<Blob>(parts.path, body, config)
+  else if (endpoint.method === 'patch') blob = await api.patch<Blob>(parts.path, body, config)
+  else if (endpoint.method === 'delete') {
+    blob = await api.delete<Blob>(parts.path, body === undefined ? config : { ...config, data: body })
+  } else {
+    throw new Error(`[MINT SDK] Unsupported plugin endpoint method: ${endpoint.method}`)
+  }
 
   if (options.filename) {
     downloadBlob(blob, options.filename, {

package/src/types/analysisArtifactTypes.ts

@@ -38,6 +38,15 @@ export interface AnalysisArtifactListResponse {
   artifacts: AnalysisArtifactSummary[]
 }
 
+/** Stable identity used when one plugin opens another plugin's artifact. */
+export interface AnalysisArtifactTarget {
+  experimentId: number
+  artifactPluginId: string
+  artifactKey: string
+  /** Optional lookup hint. The stable identity remains the three fields above. */
+  artifactId?: number
+}
+
 /** Body of PATCH /experiments/{id}/analysis-artifacts/{artifactId}. */
 export interface AnalysisArtifactMetadataUpdate {
   display_name?: string

package/src/types/index.ts

@@ -182,6 +182,7 @@ export type {
   AnalysisArtifactSummary,
   AnalysisArtifactDetail,
   AnalysisArtifactListResponse,
+  AnalysisArtifactTarget,
   AnalysisArtifactMetadataUpdate,
   ArtifactSaveMode,
   ArtifactFileSource,